@sigmacomputing/plugin 0.7.57 → 1.0.0-rc.1

package/README.md

@@ -1,14 +1,788 @@
-# Install the dependencies
+<p align="center">
+  <a href="https://github.com/sigmacomputing/plugin">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://github.com/sigmacomputing/plugin/blob/main/assets/sigma-logo-dark.svg">
+      <img alt="Sigma Logo" src="https://github.com/sigmacomputing/plugin/blob/main/assets/sigma-logo-light.svg" width="400px">
+    </picture>
+  </a>
+</p>
 
+Sigma Computing Plugins provides an API for third-party applications add
+additional functionality into an existing Sigma workbook.
+
+Plugins are built using Sigma’s Plugin API. This API communicates data and
+interaction events between a Sigma workbook and the plugin. Plugins are hosted
+by their developer and rendered in an iframe in Sigma.
+
+## Requirements
+
+To test your plugin in Sigma Plugin Dev Playground, you must:
+
+- Have an Admin, Creator or Explorer account type
+- Have Can Edit permission on the work
+- Be in the workbook’s Edit mode
+
+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
+
+- Have "can edit" permission on the workbook
+- Be in the workbook’s Edit mode
+
+Your plugin must be a Javascript-based project and run in the browser.
+
+## Getting Started
+
+### Installation
+
+Provided you have already followed the steps to create a plugin and a plugin
+development environment, you can install `@sigmacomputing/plugin` using one of
+the following commands
+
+```sh
+yarn add @sigmacomputing/plugin
+# or
+npm install @sigmacomputing/plugin
+```
+
+If you have yet to set up your development environment, follow one of the setup
+guides below
+
+### Create a Development Project
+
+At Sigma, we use React for all of our frontend development. This was taken into
+consideration when building Sigma’s Plugin feature.
+
+While you are not required to use React for your plugin, it must be written in
+Javascript and React is recommended. We support both a standard Javascript API
+and a React Hooks API.
+
+#### Create a Project with React
+
+1. Open your terminal and navigate to the directory you want to create your
+   project in.
+2. Create your new project. We recommend using Facebook’s
+   [`create-react-app`](https://create-react-app.dev/).
+
+   ```sh
+   npx create-react-app <my-cool-plugin>
+   ```
+
+3. Navigate to the project's main directory.
+
+   ```sh
+   cd <my-cool-plugin>
+   ```
+
+4. Use your package manager to install Sigma’s plugin library. We recommend
+   using `yarn`.
+
+   ```sh
+   yarn add @sigmacomputing/plugin
+   ```
+
+5. Spin up your local development server.
+
+   ```sh
+   yarn && yarn start
+   ```
+
+6. Start developing:
+
+   - Get started with Sigma’s Plugin APIs.
+   - Test your plugin directly in a Sigma workbook using the Sigma Plugin Dev
+     Playground.
+   - By default, Create React App dev servers run on http://localhost:3000.
+
+## Testing your Plugin
+
+Plugin developers should have access to a special plugin called Sigma Plugin Dev
+Playground. This plugin is available from any workbook and points to
+http://localhost:3000, by default.
+
+If you cannot find this plugin, or would like a development playground with an
+alternative default host, please contact your Organization Admin with a request
+to Register a Plugin with its production URL set to your preferred development
+URL.
+
+### Using the Development Playground
+
+Before you start:
+
+- Set your plugin’s development URL to http://localhost:3000.
+- Start your plugin locally
+
+  > Note: If you followed our recommendations under
+  > [#create-a-development-project](#create-a-development-project), enter the
+  > following command in your terminal:
+  >
+  > ```sh
+  > yarn && yarn start
+  > ```
+
+1. Create/open a workbook.
+2. In the workbook header, click Edit.
+3. Click the + button in the sidebar, to open the workbook’s ADD NEW panel.
+4. Select the PLUGINS element type, located under UI ELEMENTS.
+5. The editor panel will show you a list of available plugins. Select Sigma
+   Plugin Dev Playground.
+6. Your new plugin element will appear on the page.
+
+> **Note:**
+> The editor panel will only display content if you have configured your plugin
+> using Sigma’s plugin [Configuration API](#documentation).
+> Likewise, the element will only display content if your plugin is configured to display content.
+> If you change a plugin's configuration options, input values will need to be
+> re-added in the editor panel.
+
+**Now what?**
+
+- You can refresh your plugin as you make changes to its code. This option is
+  available from the element’s menu.
+- You are responsible for hosting your plugin. [Learn more](#host-your-plugin).
+- When you’re ready to register your plugin, [Add your custom your
+  Plugin](https://help.sigmacomputing.com/hc/en-us/articles/4410105794963) with
+  Sigma.
+
+## Documentation
+
+#### CustomPluginConfigOptions
+
+A plugin can be configured with any number of configuration fields. Each field
+type has its own configuration options. Each field type is also garunteed to
+have a the following options:
+
+- `name : string` - the name of the field
+- `type : string` - the field type
+- `label : string (optional)` - a display name for the field
+
+<details>
+<summary>Full CustomPluginConfigOptions Type</summary>
+
+```ts
+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
+      secure?: boolean; // if true will omit from prehydrated configs
+      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;
+    };
+```
+
+</details>
+
+**Group**
+
+Can be used to identify a group of related fields
+
+**Element**
+
+A custom element that is added by your plugin
+
+**Column**
+
+A custom column configuration that your plugin uses
+
+Additional Fields
+
+- `allowedTypes : ValueType[] (optional)` - the allowed data types that this
+  column can contain where `ValueType` has the following type:
+
+  ```ts
+  type ValueType =
+    | 'boolean'
+    | 'datetime'
+    | 'number'
+    | 'integer'
+    | 'text'
+    | 'variant'
+    | 'link'
+    | 'error';
+  ```
+
+- `source : string` - the data source that should be used to supply this field
+- `allowMultiple : boolean` - whether multiple columns should be allowed as
+  input for this field
+
+**Text**
+
+A configurable text input for your plugin
+
+Additional Fields
+
+- `source : string (optional)` - the data source that should be used to supply this field
+- `secure : boolean (optional)` - whether to omit input from pre-hydrated configs
+- `multiline : boolean (optional)` - whether this text input should allow
+  multiple lines
+- `placeholder : string (optional)` - the placeholder for this input field
+- `defaultValue : string (optional)` - the default value for this input field
+
+**Toggle**
+
+A configurable toggle for your plugin
+
+Additional Fields
+
+- `source : string (optional)` - the data source that should be used to supply this field
+- `defaultValue : boolean (optional)` - the default value for this input field
+
+**Checkbox**
+
+A configurable checkbox for your plugin
+
+Additional Fields
+
+- `source : string (optional)` - the data source that should be used to supply this field
+- `defaultValue : boolean (optional)` - the default value for this input field
+
+**Radio**
+
+A configurable radio button for your plugin
+
+Additional Fields
+
+- `source : string (optional)` - the data source that should be used to supply
+  this field
+- `values : string[]` - the options to show for this input field
+- `singleLine : boolean (optional)` - whether to display options on a single
+  line. Good for (2-3) options
+- `defaultValue : boolean (optional)` - the default value for this input field
+
+**Dropdown**
+
+A configurable dropdown for your plugin
+
+Additional Fields
+
+- `source : string (optional)` - the data source that should be used to supply
+  this field
+- `values : string[]` - the options to show for this input field
+- `width : string (optional)` - how wide the dropdown should be in pixels
+- `defaultValue : boolean (optional)` - the default value for this input field
+
+**Color**
+
+A configurable color picker for your plugin
+
+Additional Fields
+
+- `source : string (optional)` - the data source that should be used to supply
+  this field
+
+**Variable**
+
+A configurable workbook variable to control other elements within your workbook
+
+Additional Fields
+
+- `allowedTypes : ControlType[] (optional)` - the allowed control types that this
+  variable can use where `ControlType` has the following type:
+
+  ```ts
+  type ControlType =
+    | 'boolean'
+    | 'date'
+    | 'number'
+    | 'text'
+    | 'text-list'
+    | 'number-list'
+    | 'date-list'
+    | 'number-range'
+    | 'date-range';
+  ```
+
+**Interaction**
+
+A configurable workbook interaction to interact with other charts within your workbook
+
+#### PluginInstance
+
+```ts
+interface PluginInstance<T> {
+  sigmaEnv: 'author' | 'viewer' | 'explorer';
+
+  config: {
+    /**
+     * Getter for entire Plugin Config
+     */
+    get(): Partial<T> | undefined;
+
+    /**
+     * Performs a shallow merge between current config and passed in config
+     */
+    set(config: Partial<T>): void;
+
+    /**
+     * Getter for key within plugin config
+     */
+    getKey<K extends keyof T>(key: K): Pick<T, K>;
+
+    /**
+     * Assigns key value pair within plugin
+     */
+    setKey<K extends keyof T>(key: K, value: Pick<T, K>): void;
+
+    /**
+     * Subscriber for Plugin Config
+     */
+    subscribe(listener: (arg0: T) => void): Unsubscriber;
+
+    /**
+     * Set possible options for plugin config
+     */
+    configureEditorPanel(options: CustomPluginConfigOptions[]): void;
+
+    /**
+     * Gets a static image of a workbook variable
+     */
+    getVariable(id: string): WorkbookVariable;
+
+    /**
+     * Setter for workbook variable passed in
+     */
+    setVariable(id: string, ...values: unknown[]): void;
+
+    /**
+     * Getter for interaction selection state
+     */
+    getInteraction(id: string): WorkbookSelection[];
+
+    /**
+     * Setter for interaction selection state
+     */
+    setInteraction(
+      id: string,
+      elementId: string,
+      selection: WorkbookSelection[],
+    ): void;
+
+    /**
+     * Overrider function for Config Ready state
+     */
+    setLoadingState(ready: boolean): void;
+
+    /**
+     * Allows users to subscribe to changes in the passed in variable
+     */
+    subscribeToWorkbookVariable(
+      id: string,
+      callback: (input: WorkbookVariable) => void,
+    ): Unsubscriber;
+
+    /**
+     * Allows users to subscribe to changes in the passed in interaction ID
+     */
+    subscribeToWorkbookInteraction(
+      id: string,
+      callback: (input: WorkbookSelection[]) => void,
+    ): Unsubscriber;
+  };
+
+  elements: {
+    /**
+     * Getter for Column Data by parent sheet ID
+     */
+    getElementColumns(id: string): Promise<WbElementColumns>;
+
+    /**
+     * Subscriber to changes in column data by ID
+     */
+    subscribeToElementColumns(
+      id: string,
+      callback: (cols: WbElementColumns) => void,
+    ): Unsubscriber;
+
+    /**
+     * Subscriber for the data within a given sheet
+     */
+    subscribeToElementData(
+      id: string,
+      callback: (data: WbElementData) => void,
+    ): Unsubscriber;
+  };
+
+  /**
+   * Destroys plugin instance and removes all subscribers
+   */
+  destroy(): void;
+}
+```
+
+### Framework Agnostic API
+
+#### client
+
+The client is a pre-initialized plugin instance. You can use this instance
+directly or create your own instance using `initialize`
+
+```ts
+const client: PluginInstance = initialize();
 ```
-yarn install
+
+Usage
+
+```ts
+import { client } from '@sigmacomputing/plugin';
+
+client.config.configureEditorPanel([
+  { name: 'source', type: 'element' },
+  { name: 'dimension', type: 'column', source: 'source', allowMultiple: true },
+]);
+```
+
+#### initialize()
+
+Instead of using the pre-initialized plugin instance, you can create your own
+plugin instance.
+
+```ts
+function initialize<T = {}>(): PluginInstance<T>;
 ```
 
-# Build a New Release
+Usage
+
+```ts
+import { initialize } from '@sigmacomputing/plugin';
+
+const myClient: PluginInstance = initialize();
+
+myClient.config.configureEditorPanel([
+  { name: 'source', type: 'element' },
+  { name: 'dimension', type: 'column', source: 'source', allowMultiple: true },
+]);
+```
+
+### React API
+
+#### <SigmaClientProvider />
+
+A context provider your plugin that enables all of the other React API hooks.
+You should wrap your plugin with this provider if your want to use the plugin
+hook API.
+
+```ts
+interface SigmaClientProviderProps {
+  client: PluginInstance;
+  children?: ReactNode;
+}
+
+function SigmaClientProvider(props: SigmaClientProviderProps): ReactNode;
+```
+
+#### usePlugin()
+
+Gets the entire plugin instance
+
+```ts
+function usePlugin(): PluginInstance;
+```
+
+#### useEditorPanelConfig()
+
+Provides a setter for the plugin's configuration options
+
+```ts
+function useEditorPanelConfig(nextOptions: CustomPluginConfigOptions[]): void;
+```
+
+Provides a setter for the Plugin's Config Options
+
+Arguments
+
+- `nextOptions : CustomPluginConfigOptions[]` - Updated possible Config Options
+
+#### useLoadingState()
+
+Gets the current plugin's loading stat. Returns a value and a setter allowing
+you to update the plugin's loading state
+
+```ts
+function useLoadingState(
+  initialState: boolean,
+): [boolean, (nextState: boolean) => void];
+```
+
+Arguments
+
+- `initialState : boolean` - Initial value to set loading state to
+
+#### useElementColumns()
+
+Provides the latest column values from corresponding sheet
+
+```ts
+function useElementColumns(elementId: string): WorkbookElementColumns;
+```
+
+Arguments
+
+- `elementId : string` - A workbook element’s unique identifier.
+
+Returns the column information from the specified element.
+
+```ts
+interface WorkbookElementColumn {
+  id: string;
+  name: string;
+  columnType: ValueType;
+}
+
+interface WorkbookElementColumns {
+  [colId: string]: WbElementColumn;
+}
+```
+
+#### useElementData()
+
+Provides the latest data values from corresponding sheet
+
+```ts
+function useElementData(elementId: string): WorkbookElementData;
+```
+
+Arguments
+
+- `elementId : string` - A workbook element’s unique identifier.
+
+Returns the row data from the specified element.
+
+```ts
+interface WorkbookElementData {
+  [colId: string]: any[];
+}
+```
+
+#### useVariable()
+
+Returns a given variable's value and a setter to update that variable
+
+```ts
+function useVariable(
+  variableId: string,
+): [WorkbookVariable | undefined, (...values: unknown[]) => void];
+```
+
+Arguments
+
+- `variableId : string` - The ID of the variable
+
+The returned setter function accepts 1 or more variable values expressed as an
+array or multiple parameters
+
+```ts
+function setVariableCallback(...values: unknown[]): void;
+```
+
+#### useInteraction()
+
+Returns a given interaction's selection state and a setter to update that interation
+
+```ts
+function useInteraction(
+  interactionId: string,
+  elementId: string,
+): [WorkbookSelection | undefined, (value: WorkbookSelection[]) => void];
+```
+
+Arguments
+
+- `interactionId : string` - The ID of the interaction
+- `elementId : string` - The ID of the element that this interaction is
+  associated with
+
+The returned setter function accepts an array of workbook selection elements
+
+```ts
+function setVariableCallback(value: WorkbookSelection[]): void;
+```
+
+#### useConfig()
+
+Returns the workbook element’s current configuration. If a key is provided, only
+the associated configuration is returned.
+
+```ts
+function useConfig(key?: string): any;
+```
+
+Arguments
+
+- `key : string (optional)` - The name of a key within the associated
+  `PluginConfigOptions` object
+
+## Examples
+
+Sigma’s development team has created a set of example plugins, listed below.
+
+All of our example plugins are hosted and can be added to your organization. To
+view / add an example plugin to your organization, follow the steps to register
+a plugin using its Production URL, listed below.
+
+You can also visit Sigma’s [Sample Plugin
+repository](https://github.com/sigmacomputing/sigma-sample-plugins) directly on
+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/
+
+### Use an Example in Your Organization
+
+To add an example plugin to your organization, follow the steps to [register a
+plugin](https://help.sigmacomputing.com/hc/en-us/articles/4410105794963) using
+its Production URL, listed in the [examples](#available-plugins) above.
+
+### Run an Example Locally
+
+1. Open your terminal, and navigate to the directory you want to save the example’s in.
+2. Clone Sigma’s [Sample Plugin
+   repository](https://github.com/sigmacomputing/sigma-sample-plugins).
+
+   ```sh
+   git clone https://github.com/sigmacomputing/sigma-sample-plugins.git
+   ```
+
+3. Navigate to the plugin you would like to try.
+
+   ```sh
+   cd sigma-sample-plugins/<plugin-name>
+   ```
+
+4. Run the plugin.
+
+   ```sh
+   yarn && yarn start
+   ```
+
+> **Note**: For additional instructions, visit the README file located in the main directory of any given example plugin.
+
+## Host Your Plugin
+
+As a plugin developer, you are responsible for hosting your plugin(s). If you’re
+new to hosting your own projects, here are a few popular hosting platforms you
+can get started with:
+
+- [Heroku](https://devcenter.heroku.com/)
+- [Netlify](https://www.netlify.com/)
+
+## Contributing
+
+We welcome contributions to `@sigmacomputing/plugin`!
+
+🐛 Issues, 📥 Pull requests and 🌟 Stars are always welcome.
+Read our [contributing
+guide](https://github.com/sigmacomputing/plugin/blob/main/CONTRIBUTING.md) to
+get started.
+
+**yarn format**
+
+Format your code to match the sigmacomputing style guide
+
+**yarn test**
 
-- Pull down changes from master
-- Create a new branch
-- Bump the version in package.json `npm version patch`
-- Submit for review
+Check if the unit tests all pass
 
-After that is checked in, switch to master, and run `npm publish`
+> You can also run the tests in `--watch` mode with **yarn test:watch**