@sigmacomputing/plugin 1.1.1 → 1.2.0

package/dist/esm/index.d.ts

@@ -0,0 +1,438 @@
+import * as React from "react";
+
+//#region src/types.d.ts
+type ScalarType = 'boolean' | 'datetime' | 'number' | 'integer' | 'text';
+type PrimitiveType = ScalarType | 'variant' | 'link';
+type ValueType = PrimitiveType | 'error';
+/**
+ * All mutable workbook control variable types
+ */
+type ControlType = 'boolean' | 'date' | 'number' | 'text' | 'text-list' | 'number-list' | 'date-list' | 'number-range' | 'date-range';
+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
+ */
+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
+ */
+interface WorkbookVariable {
+  name: string;
+  defaultValue: {
+    type: string;
+    value: any;
+  };
+}
+/**
+ * @typedef {object} UrlParameter
+ * @property {string} value Current url value
+ */
+interface UrlParameter {
+  value: string;
+}
+type WorkbookSelection = Record<string, {
+  type: string;
+  val?: unknown;
+}>;
+type PluginMessageResponse = MessageEvent<{
+  type: string;
+  result: any[];
+  error: any;
+}>;
+interface WbElement {
+  id: string;
+}
+/**
+ * @typedef {object} WorkbookElementData
+ * @property {Object<string, any>} data Workbook data sorted by column ID
+ */
+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
+ */
+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
+ */
+interface WorkbookElementColumns {
+  [colId: string]: WorkbookElementColumn;
+}
+/**
+ * Function to Unsubscribe from the corresponding elements
+ * @typedef {() => void} Unsubscriber
+ */
+type Unsubscriber = () => void;
+interface CustomPluginConfigOptionBase {
+  name: string;
+  label?: string;
+}
+interface CustomPluginConfigGroup extends CustomPluginConfigOptionBase {
+  type: 'group';
+}
+interface CustomPluginConfigElement extends CustomPluginConfigOptionBase {
+  type: 'element';
+}
+interface CustomPluginConfigColumn extends CustomPluginConfigOptionBase {
+  type: 'column';
+  allowedTypes?: ValueType[];
+  source: string;
+  allowMultiple: boolean;
+}
+interface CustomPluginConfigText extends CustomPluginConfigOptionBase {
+  type: 'text';
+  source?: string;
+  secure?: boolean;
+  multiline?: boolean;
+  placeholder?: string;
+  defaultValue?: string;
+}
+interface CustomPluginConfigToggle extends CustomPluginConfigOptionBase {
+  type: 'toggle';
+  source?: string;
+  defaultValue?: boolean;
+}
+interface CustomPluginConfigCheckbox extends CustomPluginConfigOptionBase {
+  type: 'checkbox';
+  source?: string;
+  defaultValue?: boolean;
+}
+interface CustomPluginConfigRadio extends CustomPluginConfigOptionBase {
+  type: 'radio';
+  source?: string;
+  singleLine?: boolean;
+  values: string[];
+  defaultValue?: string;
+}
+interface CustomPluginConfigDropdown extends CustomPluginConfigOptionBase {
+  type: 'dropdown';
+  source?: string;
+  width?: string;
+  values: string[];
+  defaultValue?: string;
+}
+interface CustomPluginConfigColor extends CustomPluginConfigOptionBase {
+  type: 'color';
+  source?: string;
+}
+interface CustomPluginConfigVariable extends CustomPluginConfigOptionBase {
+  type: 'variable';
+  allowedTypes?: ControlType[];
+}
+interface CustomPluginConfigInteraction extends CustomPluginConfigOptionBase {
+  type: 'interaction';
+}
+interface CustomPluginConfigActionTrigger extends CustomPluginConfigOptionBase {
+  type: 'action-trigger';
+}
+interface CustomPluginConfigActionEffect extends CustomPluginConfigOptionBase {
+  type: 'action-effect';
+}
+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
+ */
+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
+ */
+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;
+}
+//#endregion
+//#region src/react/hooks.d.ts
+/**
+ * Gets the entire plugin instance
+ * @returns {PluginInstance} Context for the current plugin instance
+ */
+declare function usePlugin(): PluginInstance<any>;
+/**
+ * Provides a setter for the Plugin's Config Options
+ * @param {CustomPluginConfigOptions[]} nextOptions Updated possible Config Options
+ */
+declare function useEditorPanelConfig(nextOptions: CustomPluginConfigOptions[]): void;
+/**
+ * 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
+ */
+declare function useLoadingState(initialState: boolean): [boolean, (nextState: boolean) => void];
+/**
+ * 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
+ */
+declare function useElementColumns(configId: string): WorkbookElementColumns;
+/**
+ * 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
+ */
+declare function useElementData(configId: string): WorkbookElementData;
+/**
+ * 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
+ */
+declare function usePaginatedElementData(configId: string): [WorkbookElementData, () => void];
+/**
+ * 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
+ */
+declare function useConfig(key?: string): any;
+/**
+ * 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
+ */
+declare function useVariable(id: string): [WorkbookVariable | undefined, Function];
+/**
+ * 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
+ */
+declare function useUrlParameter(id: string): [UrlParameter | undefined, (value: string) => void];
+/**
+ * @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
+ */
+declare function useInteraction(id: string, elementId: string): [unknown, Function];
+/**
+ * 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
+ */
+declare function useActionTrigger(configId: string): () => void;
+/**
+ * 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
+ */
+declare function useActionEffect(configId: string, effect: () => void): void;
+/**
+ * React hook for accessing plugin style with live updates
+ * @returns {PluginStyle | undefined} Style properties from the workbook if available
+ */
+declare function usePluginStyle(): PluginStyle | undefined;
+//#endregion
+//#region src/react/Provider.d.ts
+interface SigmaClientProviderProps<T = any> {
+  client: PluginInstance<T>;
+  children?: React.ReactNode;
+}
+declare function SigmaClientProvider<T = any>(props: SigmaClientProviderProps<T>): React.JSX.Element;
+//#endregion
+//#region src/client.d.ts
+declare const client: PluginInstance<{}>;
+//#endregion
+//#region src/utils/polyfillRequestAnimationFrame.d.ts
+/**
+ * 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
+ */
+declare function polyfillRequestAnimationFrame(window: Window): void;
+//#endregion
+export { ControlType, CustomPluginConfigActionEffect, CustomPluginConfigActionTrigger, CustomPluginConfigCheckbox, CustomPluginConfigColor, CustomPluginConfigColumn, CustomPluginConfigDropdown, CustomPluginConfigElement, CustomPluginConfigGroup, CustomPluginConfigInteraction, CustomPluginConfigOptionBase, CustomPluginConfigOptions, CustomPluginConfigRadio, CustomPluginConfigText, CustomPluginConfigToggle, CustomPluginConfigUrlParameter, CustomPluginConfigVariable, PluginConfig, PluginInstance, PluginMessageResponse, PluginStyle, PrimitiveType, ScalarType, SigmaClientProvider, type SigmaClientProviderProps, Unsubscriber, UrlParameter, ValueType, WbElement, WorkbookElementColumn, WorkbookElementColumns, WorkbookElementData, WorkbookSelection, WorkbookVariable, client, polyfillRequestAnimationFrame, useActionEffect, useActionTrigger, useConfig, useEditorPanelConfig, useElementColumns, useElementData, useInteraction, useLoadingState, usePaginatedElementData, usePlugin, usePluginStyle, useUrlParameter, useVariable };
+//# sourceMappingURL=index.d.ts.map