@sigmacomputing/plugin 1.0.4 → 1.1.0-alpha.1

package/src/client/initialize.ts

@@ -0,0 +1,196 @@
+import type {
+  PluginConfig,
+  PluginInstance,
+  PluginMessageResponse,
+  WorkbookSelection,
+  WorkbookVariable,
+  Unsubscriber,
+} from '../types';
+
+export function initialize<T = {}>(): PluginInstance<T> {
+  const pluginConfig: Partial<PluginConfig<T>> = {
+    config: {} as T,
+  };
+
+  let subscribedInteractions: Record<string, WorkbookSelection[]> = {};
+  let subscribedWorkbookVars: Record<string, WorkbookVariable> = {};
+
+  const listeners: {
+    [event: string]: Function[];
+  } = {};
+
+  for (const [key, value] of new URL(
+    document.location.toString(),
+  ).searchParams.entries())
+    pluginConfig[key] = JSON.parse(value);
+
+  const listener = (e: PluginMessageResponse) => {
+    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: PluginConfig<T>) => {
+    Object.assign(pluginConfig, config);
+    emit('config', pluginConfig.config ?? {});
+  });
+
+  // send initialize event
+  void execPromise('wb:plugin:init', __VERSION__).then(config => {
+    Object.assign(pluginConfig, config);
+    emit('init', pluginConfig);
+    emit('config', pluginConfig.config);
+  });
+
+  on(
+    'wb:plugin:variable:update',
+    (updatedVariables: Record<string, WorkbookVariable>) => {
+      subscribedWorkbookVars = {};
+      Object.assign(subscribedWorkbookVars, updatedVariables);
+    },
+  );
+
+  on('wb:plugin:selection:update', (updatedInteractions: unknown) => {
+    subscribedInteractions = {};
+    Object.assign(subscribedInteractions, updatedInteractions);
+  });
+
+  function on(event: string, listener: Function) {
+    listeners[event] = listeners[event] || [];
+    listeners[event].push(listener);
+  }
+
+  function off(event: string, listener: Function) {
+    if (listeners[event] == null) return;
+    listeners[event] = listeners[event].filter(a => a !== listener);
+  }
+
+  function emit(event: string, ...args: any) {
+    Object.values(listeners[event] || []).forEach(fn => fn(...args));
+  }
+
+  function execPromise<R>(event: string, ...args: any): Promise<R> {
+    return new Promise((resolve, reject) => {
+      const callback = (data: R, error: any) => {
+        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: {
+      // @ts-ignore
+      getKey(key) {
+        return pluginConfig?.config?.[key]!;
+      },
+      get() {
+        return pluginConfig.config;
+      },
+      set(partialConfig) {
+        void execPromise('wb:plugin:config:update', partialConfig);
+      },
+      setKey(key, value) {
+        void execPromise('wb:plugin:config:update', {
+          [key]: value,
+        });
+      },
+      subscribe(listener) {
+        on('config', listener);
+        return () => off('config', listener);
+      },
+      getVariable(id: string): WorkbookVariable {
+        return subscribedWorkbookVars[id];
+      },
+      setVariable(id: string, ...values: unknown[]) {
+        void execPromise('wb:plugin:variable:set', id, ...values);
+      },
+      getInteraction(id: string) {
+        return subscribedInteractions[id];
+      },
+      setInteraction(
+        id: string,
+        elementId: string,
+        selection:
+          | string[]
+          | Array<Record<string, { type: string; val?: unknown }>>,
+      ) {
+        void execPromise('wb:plugin:selection:set', id, elementId, selection);
+      },
+      configureEditorPanel(options) {
+        void execPromise('wb:plugin:config:inspector', options);
+      },
+      setLoadingState(loadingState) {
+        void execPromise('wb:plugin:config:loading-state', loadingState);
+      },
+      subscribeToWorkbookVariable(
+        id: string,
+        callback: (input: WorkbookVariable) => void,
+      ): Unsubscriber {
+        const setValues = (values: Record<string, WorkbookVariable>) => {
+          callback(values[id]);
+        };
+        on('wb:plugin:variable:update', setValues);
+        return () => {
+          off('wb:plugin:variable:update', setValues);
+        };
+      },
+      subscribeToWorkbookInteraction(
+        id: string,
+        callback: (input: WorkbookSelection[]) => void,
+      ): Unsubscriber {
+        const setValues = (values: Record<string, WorkbookSelection[]>) => {
+          callback(values[id]);
+        };
+        on('wb:plugin:selection:update', setValues);
+        return () => {
+          off('wb:plugin:selection:update', setValues);
+        };
+      },
+    },
+    elements: {
+      getElementColumns(id) {
+        return execPromise('wb:plugin:element:columns:get', id);
+      },
+      subscribeToElementColumns(id, callback) {
+        const eventName = `wb:plugin:element:${id}:columns`;
+        on(eventName, callback);
+        void execPromise('wb:plugin:element:subscribe:columns', id);
+
+        return () => {
+          off(eventName, callback);
+          void execPromise('wb:plugin:element:unsubscribe:columns', id);
+        };
+      },
+      subscribeToElementData(id, callback) {
+        const eventName = `wb:plugin:element:${id}:data`;
+        on(eventName, callback);
+        void execPromise('wb:plugin:element:subscribe:data', id);
+
+        return () => {
+          off(eventName, callback);
+          void execPromise('wb:plugin:element:unsubscribe:data', id);
+        };
+      },
+    },
+    destroy() {
+      Object.keys(listeners).forEach(event => delete listeners[event]);
+      window.removeEventListener('message', listener, false);
+    },
+  };
+}

package/src/globals.d.ts

@@ -0,0 +1,5 @@
+export {};
+
+declare global {
+  const __VERSION__: string;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './client';
+export * from './types';
+
+export { polyfillRequestAnimationFrame } from './utils/polyfillRequestAnimationFrame';

package/src/types/index.ts

@@ -0,0 +1,322 @@
+export type ScalarType = 'boolean' | 'datetime' | 'number' | 'integer' | 'text';
+export type PrimitiveType = ScalarType | 'variant' | 'link';
+export type ValueType = PrimitiveType | 'error';
+
+/**
+ * All mutable workbook control variable types
+ */
+export type ControlType =
+  | 'boolean'
+  | 'date'
+  | 'number'
+  | 'text'
+  | 'text-list'
+  | 'number-list'
+  | 'date-list'
+  | 'number-range'
+  | 'date-range';
+
+export interface PluginConfig<T> {
+  id: string;
+  config: T;
+  screenshot: boolean;
+  [key: string]: any;
+}
+
+/**
+ * @typedef {object} WorkbookVariable
+ * @property {string} name Name of Control Variable within Workbook
+ * @property {{string}} defaultValue Current Value containing at least type as string
+ */
+export interface WorkbookVariable {
+  name: string;
+  defaultValue: { type: string };
+}
+
+export type WorkbookSelection = Record<string, { type: string; val?: unknown }>;
+
+export type PluginMessageResponse = MessageEvent<{
+  type: string;
+  result: any[];
+  error: any;
+}>;
+
+export interface WbElement {
+  id: string;
+}
+
+/**
+ * @typedef {object} WorkbookElementData
+ * @property {Object<string, any>} data Workbook data sorted by column ID
+ */
+export interface WorkbookElementData {
+  [colId: string]: any[];
+}
+
+/**
+ * Column data
+ * @typedef {object} WorkbookElementColumn
+ * @property {string} id Column ID
+ * @property {string} name Column Name
+ * @property {string} columnType Type of data contained within column
+ */
+export interface WorkbookElementColumn {
+  id: string;
+  name: string;
+  columnType: ValueType;
+}
+
+/**
+ * Record of Column data with corresponding IDs
+ * @typedef {object} WorkbookElementColumns
+ * @property {Object<string, WorkbookElementColumn>} column Column ID and corresponding column data
+ */
+export interface WorkbookElementColumns {
+  [colId: string]: WorkbookElementColumn;
+}
+
+/**
+ * Function to Unsubscribe from the corresponding elements
+ * @typedef {() => void} Unsubscriber
+ */
+export type Unsubscriber = () => void;
+
+/**
+ * Different types Plugin Config Options
+ * @typedef {object} CustomPluginConfigOptions
+ * @property {string} type Type of config option
+ * @property {string} name Name ID of config option
+ * @property {(string | undefined)} label Displayed label for config option
+ */
+export type CustomPluginConfigOptions =
+  | {
+      type: 'group';
+      name: string;
+      label?: string;
+    }
+  | {
+      type: 'element';
+      name: string;
+      label?: string;
+    }
+  | {
+      type: 'column';
+      name: string;
+      label?: string;
+      allowedTypes?: ValueType[];
+      source: string;
+      allowMultiple: boolean;
+    }
+  | {
+      type: 'text';
+      name: string;
+      label?: string;
+      source?: string; // can point to a group or element config
+      // if true will omit from prehydrated configs passed through querystring
+      secure?: boolean;
+      multiline?: boolean;
+      placeholder?: string;
+      defaultValue?: string;
+    }
+  | {
+      type: 'toggle';
+      name: string;
+      label?: string;
+      source?: string;
+      defaultValue?: boolean;
+    }
+  | {
+      type: 'checkbox';
+      name: string;
+      label?: string;
+      source?: string;
+      defaultValue?: boolean;
+    }
+  | {
+      type: 'radio';
+      name: string;
+      label?: string;
+      source?: string;
+      values: string[];
+      singleLine?: boolean;
+      defaultValue?: string;
+    }
+  | {
+      type: 'dropdown';
+      name: string;
+      label?: string;
+      source?: string;
+      width?: string;
+      values: string[];
+      defaultValue?: string;
+    }
+  | {
+      type: 'color';
+      name: string;
+      label?: string;
+      source?: string;
+    }
+  | {
+      type: 'variable';
+      name: string;
+      label?: string;
+      allowedTypes?: ControlType[];
+    }
+  | {
+      type: 'interaction';
+      name: string;
+      label?: string;
+    };
+
+/**
+ * @typedef {object} PluginInstance
+ * @template T Type of Config passed in
+ * @property {string} sigmaEnv Permissions within Sigma Environment
+ * @property {object} config Set of helper functions for interacting with Plugin Config
+ * @property {object} elements Set of helper functions for interacting with Workbook Element Data
+ * @property {Function} destroy Destroys Plugin Instance and removes all subscriptions
+ */
+export interface PluginInstance<T = any> {
+  sigmaEnv: 'author' | 'viewer' | 'explorer';
+
+  config: {
+    /**
+     * Getter for entire Plugin Config
+     * @template T Config type to be passed in
+     * @returns {Partial<T>} Current Plugin Config
+     */
+    get(): Partial<T> | undefined;
+
+    /**
+     * Performs a shallow merge between current config and passed in config
+     * @template T Config type to be passed in
+     * @param {Partial<T>} config Config to directly assign
+     */
+    set(config: Partial<T>): void;
+
+    /**
+     * Getter for key within plugin config
+     * @template K Possible key within CustomPluginConfigOptions
+     * @param {K} key Key within config to retrieve
+     * @returns Value within config for passed in key
+     */
+    getKey<K extends keyof T>(key: K): Pick<T, K>;
+
+    /**
+     * Assigns key value pair within plugin
+     * @template K Possible key within CustomPluginConfigOptions
+     * @template V Value corresponding to K
+     * @param {K} key Key within config to set
+     * @param {V} value New value to set key to
+     */
+    setKey<K extends keyof T>(key: K, value: Pick<T, K>): void;
+
+    /**
+     * Subscriber for Plugin Config
+     * @param {Function} listener Function to be called upon changes to Plugin Config
+     */
+    subscribe(listener: (arg0: T) => void): Unsubscriber;
+
+    /**
+     * Set possible options for plugin config
+     * @param {CustomPluginConfigOptions[]} options Possible config options
+     */
+    configureEditorPanel(options: CustomPluginConfigOptions[]): void;
+
+    /**
+     * Gets a static image of a workbook variable
+     * @param {string} id ID of the workbook variable in config
+     * @returns {WorkbookVariable} Current value of the workbook variable
+     */
+    getVariable(id: string): WorkbookVariable;
+
+    /**
+     * Setter for workbook variable passed in
+     * @param {string} id ID of the workbook variable in config
+     * @param {unknown[]} values Values to assign to the workbook variable
+     */
+    setVariable(id: string, ...values: unknown[]): void;
+
+    /**
+     * Getter for interaction selection state
+     * @param {string} id ID from interaction type in Plugin Config
+     */
+    getInteraction(id: string): WorkbookSelection[];
+
+    /**
+     * Setter for interaction selection state
+     * @param {string} id ID from interaction type in Plugin Config
+     * @param {string} elementId Source element ID from element type in Plugin Config
+     * @param {Object} selection List of column IDs or Columns and values and key-value pairs to select
+     */
+    setInteraction(
+      id: string,
+      elementId: string,
+      selection: WorkbookSelection[],
+    ): void;
+
+    /**
+     * Overrider function for Config Ready state
+     * @param {boolean} loadingState Boolean representing if Plugin Config is still loading
+     */
+    setLoadingState(ready: boolean): void;
+
+    /**
+     * Allows users to subscribe to changes in the passed in variable
+     * @param {string} id ID of the workbook variable in config
+     * @callback callback Function to be called upon receiving an updated workbook variable
+     * @returns {Unsubscriber} A callable unsubscriber
+     */
+    subscribeToWorkbookVariable(
+      id: string,
+      callback: (input: WorkbookVariable) => void,
+    ): Unsubscriber;
+
+    /**
+     * Allows users to subscribe to changes in the passed in interaction ID
+     * @param {string} id ID of the interaction variable within Plugin Config
+     * @callback callback Function to be called upon receiving an updated interaction selection state
+     * @returns {Unsubscriber} A callable unsubscriber
+     */
+    subscribeToWorkbookInteraction(
+      id: string,
+      callback: (input: WorkbookSelection[]) => void,
+    ): Unsubscriber;
+  };
+
+  elements: {
+    /**
+     * Getter for Column Data by parent sheet ID
+     * @param {string} id Sheet ID to retrieve columns from
+     * @returns {WorkbookElementColumns} Column values contained within corresponding sheet
+     */
+    getElementColumns(id: string): Promise<WorkbookElementColumns>;
+
+    /**
+     * Subscriber to changes in column data by ID
+     * @param {string} id Column ID to subscribe to
+     * @callback callback Callback function to be called upon changes to column data
+     * @returns {Unsubscriber} Callable unsubscriber to column data changes
+     */
+    subscribeToElementColumns(
+      id: string,
+      callback: (cols: WorkbookElementColumns) => void,
+    ): Unsubscriber;
+
+    /**
+     * Subscriber for the data within a given sheet
+     * @param {string} id Sheet ID to get element data from
+     * @callback callback Function to call on data passed in
+     * @returns {Unsubscriber} A callable unsubscriber to changes in the data
+     */
+    subscribeToElementData(
+      id: string,
+      callback: (data: WorkbookElementData) => void,
+    ): Unsubscriber;
+  };
+
+  /**
+   * Destroys plugin instance and removes all subscribers
+   */
+  destroy(): void;
+}

package/src/utils/polyfillRequestAnimationFrame.ts

@@ -0,0 +1,13 @@
+/**
+ * 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
+ * @param w Window Object
+ */
+export function polyfillRequestAnimationFrame(window: Window) {
+  if ('requestAnimationFrame' in window) {
+    window.requestAnimationFrame = (handler: TimerHandler): number =>
+      window.setTimeout(handler, 1000 / 60);
+    window.cancelAnimationFrame = (id?: number) => window.clearTimeout(id);
+  }
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2021 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
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.