@sigmacomputing/plugin 1.1.0 → 1.2.0

package/src/react/hooks.ts

@@ -0,0 +1,298 @@
+import * as React from 'react';
+
+import {
+  PluginInstance,
+  CustomPluginConfigOptions,
+  WorkbookElementColumns,
+  WorkbookElementData,
+  WorkbookSelection,
+  WorkbookVariable,
+  PluginStyle,
+  UrlParameter,
+} from '../types';
+import { deepEqual } from '../utils/deepEqual';
+
+import { PluginContext } from './Context';
+
+/**
+ * Gets the entire plugin instance
+ * @returns {PluginInstance} Context for the current plugin instance
+ */
+export function usePlugin(): PluginInstance<any> {
+  return React.useContext(PluginContext);
+}
+
+/**
+ * Provides a setter for the Plugin's Config Options
+ * @param {CustomPluginConfigOptions[]} nextOptions Updated possible Config Options
+ */
+export function useEditorPanelConfig(
+  nextOptions: CustomPluginConfigOptions[],
+): void {
+  const client = usePlugin();
+  const optionsRef = React.useRef({});
+
+  React.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
+ */
+export function useLoadingState(
+  initialState: boolean,
+): [boolean, (nextState: boolean) => void] {
+  const client = usePlugin();
+  const [loading, setLoading] = React.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
+ */
+export function useElementColumns(configId: string): WorkbookElementColumns {
+  const client = usePlugin();
+  const [columns, setColumns] = React.useState<WorkbookElementColumns>({});
+
+  React.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
+ */
+export function useElementData(configId: string): WorkbookElementData {
+  const client = usePlugin();
+  const [data, setData] = React.useState<WorkbookElementData>({});
+
+  React.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
+ */
+export function usePaginatedElementData(
+  configId: string,
+): [WorkbookElementData, () => void] {
+  const client = usePlugin();
+  const [data, setData] = React.useState<WorkbookElementData>({});
+
+  const loadMore = React.useCallback(() => {
+    if (configId) {
+      client.elements.fetchMoreElementData(configId);
+    }
+  }, [configId, client.elements]);
+
+  React.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
+ */
+export function useConfig(key?: string): any {
+  const client = usePlugin();
+  const [config, setConfig] = React.useState<any>(
+    key != null ? client.config.getKey(key) : client.config.get(),
+  );
+
+  React.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
+ */
+export function useVariable(
+  id: string,
+): [WorkbookVariable | undefined, Function] {
+  const client = usePlugin();
+  const [workbookVariable, setWorkbookVariable] =
+    React.useState<WorkbookVariable>();
+
+  const isFirstRender = React.useRef<boolean>(true);
+
+  React.useEffect(() => {
+    if (isFirstRender.current) {
+      setWorkbookVariable(client.config.getVariable(id));
+      isFirstRender.current = false;
+    }
+    return client.config.subscribeToWorkbookVariable(id, setWorkbookVariable);
+  }, [client, id]);
+
+  const setVariable = React.useCallback(
+    (...values: unknown[]) => client.config.setVariable(id, ...values),
+    [id, client.config],
+  );
+
+  return [workbookVariable, setVariable];
+}
+
+/**
+ * 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
+ */
+export function useUrlParameter(
+  id: string,
+): [UrlParameter | undefined, (value: string) => void] {
+  const client = usePlugin();
+  const [urlParameter, setUrlParameter] = React.useState<UrlParameter>();
+
+  const isFirstRender = React.useRef<boolean>(true);
+
+  React.useEffect(() => {
+    if (isFirstRender.current) {
+      setUrlParameter(client.config.getUrlParameter(id));
+      isFirstRender.current = false;
+    }
+    return client.config.subscribeToUrlParameter(id, setUrlParameter);
+  }, [client, id]);
+
+  const setter = React.useCallback(
+    (value: string) => client.config.setUrlParameter(id, value),
+    [client, id],
+  );
+
+  return [urlParameter, setter];
+}
+
+/**
+ * @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
+ */
+export function useInteraction(
+  id: string,
+  elementId: string,
+): [unknown, Function] {
+  const client = usePlugin();
+  const [workbookInteraction, setWorkbookInteraction] =
+    React.useState<WorkbookSelection[]>();
+
+  React.useEffect(() => {
+    return client.config.subscribeToWorkbookInteraction(
+      id,
+      setWorkbookInteraction,
+    );
+  }, [client, id]);
+
+  const setInteraction = React.useCallback(
+    (value: WorkbookSelection[]) => {
+      client.config.setInteraction(id, elementId, value);
+    },
+    [id, elementId, client.config],
+  );
+
+  return [workbookInteraction, setInteraction];
+}
+
+/**
+ * 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
+ */
+export function useActionTrigger(configId: string): () => void {
+  const client = usePlugin();
+
+  return React.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
+ */
+export function useActionEffect(configId: string, effect: () => void) {
+  const client = usePlugin();
+
+  const effectRef = React.useRef(effect);
+
+  React.useEffect(() => {
+    effectRef.current = effect;
+  });
+
+  React.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
+ */
+export function usePluginStyle(): PluginStyle | undefined {
+  const client = usePlugin();
+  const [style, setStyle] = React.useState<PluginStyle | undefined>();
+
+  React.useEffect(() => {
+    // Request initial style data on mount and subscribe to updates
+    void client.style.get().then(response => setStyle(response));
+    return client.style.subscribe(setStyle);
+  }, [client]);
+
+  return style;
+}

package/src/react.ts

@@ -0,0 +1,3 @@
+export * from './react/hooks';
+export type { SigmaClientProviderProps } from './react/Provider';
+export { SigmaClientProvider } from './react/Provider';

package/src/types.ts

@@ -0,0 +1,412 @@
+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;
+}
+
+/**
+ * Style colors available to plugins
+ * @typedef {object} PluginStyle
+ * @property {string} backgroundColor Background color set from workbook if any
+ */
+export interface PluginStyle {
+  backgroundColor: string;
+}
+
+/**
+ * @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; value: any };
+}
+
+/**
+ * @typedef {object} UrlParameter
+ * @property {string} value Current url value
+ */
+export interface UrlParameter {
+  value: 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;
+
+export interface CustomPluginConfigOptionBase {
+  name: string;
+  label?: string;
+}
+export interface CustomPluginConfigGroup extends CustomPluginConfigOptionBase {
+  type: 'group';
+}
+export interface CustomPluginConfigElement extends CustomPluginConfigOptionBase {
+  type: 'element';
+}
+export interface CustomPluginConfigColumn extends CustomPluginConfigOptionBase {
+  type: 'column';
+  allowedTypes?: ValueType[];
+  source: string;
+  allowMultiple: boolean;
+}
+export interface CustomPluginConfigText extends CustomPluginConfigOptionBase {
+  type: 'text';
+  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;
+}
+export interface CustomPluginConfigToggle extends CustomPluginConfigOptionBase {
+  type: 'toggle';
+  source?: string;
+  defaultValue?: boolean;
+}
+export interface CustomPluginConfigCheckbox extends CustomPluginConfigOptionBase {
+  type: 'checkbox';
+  source?: string;
+  defaultValue?: boolean;
+}
+export interface CustomPluginConfigRadio extends CustomPluginConfigOptionBase {
+  type: 'radio';
+  source?: string;
+  singleLine?: boolean;
+  values: string[];
+  defaultValue?: string;
+}
+export interface CustomPluginConfigDropdown extends CustomPluginConfigOptionBase {
+  type: 'dropdown';
+  source?: string;
+  width?: string;
+  values: string[];
+  defaultValue?: string;
+}
+export interface CustomPluginConfigColor extends CustomPluginConfigOptionBase {
+  type: 'color';
+  source?: string;
+}
+export interface CustomPluginConfigVariable extends CustomPluginConfigOptionBase {
+  type: 'variable';
+  allowedTypes?: ControlType[];
+}
+export interface CustomPluginConfigInteraction extends CustomPluginConfigOptionBase {
+  type: 'interaction';
+}
+export interface CustomPluginConfigActionTrigger extends CustomPluginConfigOptionBase {
+  type: 'action-trigger';
+}
+export interface CustomPluginConfigActionEffect extends CustomPluginConfigOptionBase {
+  type: 'action-effect';
+}
+export interface CustomPluginConfigUrlParameter extends Omit<
+  CustomPluginConfigOptionBase,
+  'label'
+> {
+  type: 'url-parameter';
+}
+
+/**
+ * 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 =
+  | CustomPluginConfigGroup
+  | CustomPluginConfigElement
+  | CustomPluginConfigColumn
+  | CustomPluginConfigText
+  | CustomPluginConfigToggle
+  | CustomPluginConfigCheckbox
+  | CustomPluginConfigRadio
+  | CustomPluginConfigDropdown
+  | CustomPluginConfigColor
+  | CustomPluginConfigVariable
+  | CustomPluginConfigInteraction
+  | CustomPluginConfigActionTrigger
+  | CustomPluginConfigActionEffect
+  | CustomPluginConfigUrlParameter;
+
+/**
+ * @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} configId ID from config of type: 'variable'
+     * @returns {WorkbookVariable} Current value of the workbook variable
+     */
+    getVariable(configId: string): WorkbookVariable;
+
+    /**
+     * Setter for workbook variable passed in
+     * @param {string} configId ID from config of type: 'variable'
+     * @param {unknown[]} values Values to assign to the workbook variable
+     */
+    setVariable(configId: string, ...values: unknown[]): void;
+
+    /**
+     * @deprecated Use Action API instead
+     * Getter for interaction selection state
+     * @param {string} configId ID from config of type: 'interaction'
+     */
+    getInteraction(configId: string): WorkbookSelection[];
+
+    /**
+     * @deprecated Use Action API instead
+     * Setter for interaction selection state
+     * @param {string} configId ID from config of type: 'interaction'
+     * @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(
+      configId: string,
+      elementId: string,
+      selection: WorkbookSelection[],
+    ): void;
+
+    /**
+     * Triggers an action based on the provided action trigger ID
+     * @param {string} configId ID from config of type: 'action-trigger'
+     */
+    triggerAction(configId: string): void;
+
+    /**
+     * Registers an effect with the provided action effect ID
+     * @param {string} configId ID from config of type: 'action-effect'
+     * @param {Function} effect The effect function to register
+     * @returns {Unsubscriber} A callable unsubscriber
+     */
+    registerEffect(configId: string, effect: () => void): () => void;
+
+    /**
+     * Tell the workbook whether the plugin is still loading. Pass false when the plugin
+     * has finished loading and is ready to be used.
+     * @param {boolean} isLoading Boolean representing if Plugin Config is still loading
+     */
+    setLoadingState(isLoading: boolean): void;
+
+    /**
+     * Allows users to subscribe to changes in the passed in variable
+     * @param {string} configId ID from config of type: 'variable'
+     * @callback callback Function to be called upon receiving an updated workbook variable
+     * @returns {Unsubscriber} A callable unsubscriber
+     */
+    subscribeToWorkbookVariable(
+      configId: string,
+      callback: (input: WorkbookVariable) => void,
+    ): Unsubscriber;
+
+    /**
+     * Allows users to subscribe to changes in the url parameter
+     * @param {string} configId ID from config of type: 'url-parameter'
+     * @callback callback Function to be called upon receiving an updated url parameter
+     * @returns {Unsubscriber} A callable unsubscriber
+     */
+    subscribeToUrlParameter(
+      configId: string,
+      callback: (input: UrlParameter) => void,
+    ): Unsubscriber;
+
+    /**
+     * Gets the current value of a url parameter
+     * @param {string} configId ID from config of type: 'url-parameter'
+     * @returns {UrlParameter} Current value of the url parameter
+     */
+    getUrlParameter(configId: string): UrlParameter;
+
+    /**
+     * Setter for url parameter
+     * @param {string} configId ID from config of type: 'url-parameter'
+     * @param {string} value Value to assign to the url parameter
+     */
+    setUrlParameter(configId: string, value: string): void;
+
+    /**
+     * @deprecated Use Action API instead
+     * Allows users to subscribe to changes in the passed in interaction ID
+     * @param {string} configId ID from the config of type: 'interaction'
+     * @callback callback Function to be called upon receiving an updated interaction selection state
+     * @returns {Unsubscriber} A callable unsubscriber
+     */
+    subscribeToWorkbookInteraction(
+      configId: string,
+      callback: (input: WorkbookSelection[]) => void,
+    ): Unsubscriber;
+  };
+
+  elements: {
+    /**
+     * Getter for Column Data by parent sheet ID
+     * @param {string} configId ID from config of type: 'element'
+     * @returns {WorkbookElementColumns} Column values contained within corresponding sheet
+     */
+    getElementColumns(configId: string): Promise<WorkbookElementColumns>;
+
+    /**
+     * Subscriber to changes in column data by ID
+     * @param {string} configId ID from config of type: 'element'
+     * @callback callback Callback function to be called upon changes to column data
+     * @returns {Unsubscriber} Callable unsubscriber to column data changes
+     */
+    subscribeToElementColumns(
+      configId: string,
+      callback: (cols: WorkbookElementColumns) => void,
+    ): Unsubscriber;
+
+    /**
+     * Subscriber for the data within a given sheet
+     * @param {string} configId ID from config of type: 'element'
+     * @callback callback Function to call on data passed in
+     * @returns {Unsubscriber} A callable unsubscriber to changes in the data
+     */
+    subscribeToElementData(
+      configId: string,
+      callback: (data: WorkbookElementData) => void,
+    ): Unsubscriber;
+
+    /**
+     * Ask sigma to load more data
+     * @param {string} configId ID from config of type: 'element'
+     */
+    fetchMoreElementData(configId: string): void;
+  };
+
+  style: {
+    /**
+     * Subscribe to style updates
+     * @param callback Function to call when style updates
+     * @returns Unsubscriber function
+     */
+    subscribe(callback: (style: PluginStyle) => void): () => void;
+
+    /**
+     * Request current style from workbook
+     * @returns Promise with current style
+     */
+    get(): Promise<PluginStyle>;
+  };
+
+  /**
+   * Destroys plugin instance and removes all subscribers
+   */
+  destroy(): void;
+}