visualifyjs 2.5.3 → 3.0.0

package/docs/docs/components/more.md

@@ -1,142 +1,183 @@
-# More components
-
-## Markdown
-
-The Markdown component is used to render markdown content on the page.
-
-
-
-## SearchBar
-
-The SearchBar component is used to search for a specific gene.
-
-### Properties
-
-The SearchBar component has the following properties:
-
--   `type` (string): The type of the component, in this case `SearchBar`.
--   `id` (string): The unique identifier of the component.
--   `row` (int): The row in which the component is to be displayed.
--   `col` (int): The column in which the component is to be displayed.
--   `config` (object): The configuration of the component.
--   `style` (object): The style of the component.
--   `title` (string): The title of the component.
-
-### config Properties
-
-The `config` object has the following properties:
-
--   `save` (boolean/String): Whether to save the search or not.
-    -   (string): The name to be saved at global data.
--   `source` (object): The source of the component.
-    -   `name` (string): The name of the source.
-    -   `url` (string): The URL of the source.
-    -   `responseKey` (string): The response key of the source.
-
-### Example
-
-```json
-{
-    "id": "mmtrbc_gene",
-    "type": "SearchBar",
-    "title": "Search Gene",
-    "config": {
-        "save": true,
-        "source": {
-            "name": "genelist",
-            "url": "https://visualify.pharmacy.arizona.edu/api/mmtrbc/genelist",
-            "responseKey": "gene"
-        }
-    }
-}
-```
-
-## List
-
-The List component is used to display a list of genes.
-
-### Properties
-
-The List component has the following properties:
-
--   `type` (string): The type of the component, in this case `List`.
--   `id` (string): The unique identifier of the component.
--   `row` (int): The row in which the component is to be displayed.
--   `col` (int): The column in which the component is to be displayed.
--   `rowspan` (int): The number of rows the component is to span.
--   `btn` (object): The button of the component.
--   `style` (object): The style of the component.
--   `title` (string): The title of the component.
-
-### example
-
-```json
-  {
-            "id": "genelist",
-            "type": "List",
-            "row": 2,
-            "col": 1,
-            "rowspan": 3,
-            "btn": {
-                "add": {
-                    "text": "Add",
-                    "show": true,
-                    "style": {
-                        "color": "white",
-                        "backgroundColor": "#FF8E8E",
-                        "fontSize": "12px",
-                        "border": "none",
-                        "cursor": "pointer"
-                    },
-                    "addfrom": "mmtrbc_gene"
-                },
-                "clear": {
-                    "text": "Clear",
-                    "show": true,
-                    "msg": "Successfully cleared the list",
-                    "style": {
-                    }
-                },
-                "remove": {
-                    "show": true,
-                    "style": {
-                        "color": "white",
-                        "backgroundColor": "#f44336",
-                    }
-                }
-            }
-        }
-```
-
-## RatioBox
-
-The RatioBox component is used to display a ratio box on the page.
-
-### Properties
-
-The RatioBox component has the following properties:
-
--   `type` (string): The type of the component, in this case `RatioBox`.
--   `id` (string): The unique identifier of the component.
--   `row` (int): The row in which the component is to be displayed.
--   `col` (int): The column in which the component is to be displayed.
--   `choice` (array): The choice of the component.
--   `style` (object): The style of the component.
--   `val` (string): Will save the choices to the name of global variable.
-
-### Example
-
-```json
-{
-    "type": "RatioBox",
-    "id": "chrom_colour",
-    "row": 2,
-    "col": 1,
-    "choice": ["Cell Type", "Stage"],
-    "style": {
-        "width": "350px"
-    },
-    "val": "chrom_colour",
-    "title": "Colour by"
-}
-```
+# Utility Components
+
+These components provide UI controls and interactive elements for page mode layouts. They work alongside visualization components to create complete data exploration interfaces.
+
+## Overview
+
+| Component | Purpose | Interactive |
+|-----------|---------|-------------|
+| SearchBar | Gene/item search with autocomplete | Yes - triggers other components |
+| List | Display and manage a list of items | Yes - add/remove/clear |
+| RatioBox | Radio button selector for options | Yes - stores selection globally |
+
+---
+
+## SearchBar
+
+The SearchBar component provides a search input with autocomplete, powered by an external data source. When a user selects a result, the value can be saved to the global data store for use by other components.
+
+### Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | string | Yes | Must be `"SearchBar"`. |
+| `id` | string | Yes | Unique identifier for the component. |
+| `row` | int | No | The row in which the component is displayed. |
+| `col` | int | No | The column in which the component is displayed. |
+| `title` | string | No | Label displayed above the search input. |
+| `config` | object | Yes | Configuration for data source and behavior. See below. |
+| `style` | object | No | CSS styles applied to the component container. |
+
+#### Config Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `save` | boolean / string | If `true`, saves the selected value to global data using the component `id` as the key. If a string, uses that string as the global data key instead. |
+| `source` | object | Defines the autocomplete data source. |
+| `source.name` | string | Name identifier for the data source. |
+| `source.url` | string | API endpoint that returns the list of searchable items. |
+| `source.responseKey` | string | Key in the API response that contains the list of items. |
+
+### Example
+
+```json
+{
+    "id": "mmtrbc_gene",
+    "type": "SearchBar",
+    "title": "Search Gene",
+    "config": {
+        "save": true,
+        "source": {
+            "name": "genelist",
+            "url": "https://visualify.pharmacy.arizona.edu/api/mmtrbc/genelist",
+            "responseKey": "gene"
+        }
+    }
+}
+```
+
+### Interaction with Other Components
+
+When `save` is enabled, the selected search result is stored in the global data store. Other components (such as charts or tables) can reference this value to filter or update their displayed data. For example, a SearchBar with `id: "mmtrbc_gene"` makes the selected gene available to any component that reads from the `mmtrbc_gene` global key.
+
+---
+
+## List
+
+The List component displays a managed list of items. Users can add items (typically from a SearchBar), remove individual items, or clear the entire list. It is commonly used to build a working set of genes or other entities for downstream analysis.
+
+### Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | string | Yes | Must be `"List"`. |
+| `id` | string | Yes | Unique identifier for the component. |
+| `row` | int | No | The row in which the component is displayed. |
+| `col` | int | No | The column in which the component is displayed. |
+| `rowspan` | int | No | The number of rows the component spans. |
+| `title` | string | No | Label displayed above the list. |
+| `btn` | object | No | Configuration for action buttons (add, remove, clear). See below. |
+| `style` | object | No | CSS styles applied to the component container. |
+
+#### Button Properties
+
+Each button (`add`, `remove`, `clear`) accepts the following:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `text` | string | Label displayed on the button. |
+| `show` | boolean | Whether the button is visible. |
+| `style` | object | CSS styles for the button. |
+| `msg` | string | Confirmation or success message (used by `clear`). |
+| `addfrom` | string | ID of the SearchBar component to pull values from (used by `add`). |
+
+### Example
+
+```json
+{
+    "id": "genelist",
+    "type": "List",
+    "row": 2,
+    "col": 1,
+    "rowspan": 3,
+    "btn": {
+        "add": {
+            "text": "Add",
+            "show": true,
+            "style": {
+                "color": "white",
+                "backgroundColor": "#FF8E8E",
+                "fontSize": "12px",
+                "border": "none",
+                "cursor": "pointer"
+            },
+            "addfrom": "mmtrbc_gene"
+        },
+        "clear": {
+            "text": "Clear",
+            "show": true,
+            "msg": "Successfully cleared the list",
+            "style": {}
+        },
+        "remove": {
+            "show": true,
+            "style": {
+                "color": "white",
+                "backgroundColor": "#f44336"
+            }
+        }
+    }
+}
+```
+
+### Interaction with Other Components
+
+The List component connects to a SearchBar through the `addfrom` property on the `add` button. In the example above, `"addfrom": "mmtrbc_gene"` pulls the currently selected value from the SearchBar with `id: "mmtrbc_gene"`. The list contents can then be consumed by visualization components that need a set of items to display.
+
+---
+
+## RatioBox
+
+The RatioBox component renders a group of radio buttons, allowing the user to select one option from a predefined set. The selected value is stored in the global data store so that other components can react to the user's choice.
+
+### Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | string | Yes | Must be `"RatioBox"`. |
+| `id` | string | Yes | Unique identifier for the component. |
+| `row` | int | No | The row in which the component is displayed. |
+| `col` | int | No | The column in which the component is displayed. |
+| `title` | string | No | Label displayed above the radio buttons. |
+| `choice` | array | Yes | Array of strings representing the available options. |
+| `val` | string | Yes | Name of the global variable where the selected choice is stored. |
+| `style` | object | No | CSS styles applied to the component container. |
+
+### Example
+
+```json
+{
+    "type": "RatioBox",
+    "id": "chrom_colour",
+    "row": 2,
+    "col": 1,
+    "choice": ["Cell Type", "Stage"],
+    "style": {
+        "width": "350px"
+    },
+    "val": "chrom_colour",
+    "title": "Colour by"
+}
+```
+
+### Interaction with Other Components
+
+The selected option is saved to the global variable specified by `val`. In the example above, choosing "Cell Type" or "Stage" updates the `chrom_colour` global variable. Visualization components (such as scatter plots or UMAP charts) can reference this variable to change their color mapping dynamically.
+
+---
+
+## See Also
+
+- [HTML Component](components/html.md) -- Render raw HTML content in page layouts.
+- [Markdown Component](components/markdown.md) -- Render Markdown content in page layouts.
+- [Page Mode Overview](bindData/bindPage.md) -- How components are arranged in page layouts.

package/docs/docs/components/plotly.md

@@ -1,62 +1,132 @@
-# Plotly Component
-
-The Plotly component is used to display a plotly plot on the page.
-
-## Properties
-
-The Plotly component has the following properties:
-
--   `type` (string): The type of the component, in this case `Plotly`.
--   `id` (string): The unique identifier of the component.
--   `row` (int): The row in which the component is to be displayed.
--   `col` (int): The column in which the component is to be displayed.
--   `rowspan` (int): The number of rows the component is to span.
--   `colspan` (int): The number of columns the component is to span.
--   `settings` (object): The settings of the component.
--   `parser` (object): The parser of the component.
--   `trigger` (object): The trigger of the component.
-
-### settings Properties
-
-The `settings` object has the following properties:
-
--   `preset` (string): The preset of the component.
--   `ignoreEmptyData` (boolean): Whether to ignore empty data or not.
-
-### parser Properties
-
-The `parser` object has the following properties:
-
--   `sources` (array): The sources of the component.
-    -   `name` (string): The name of the trigger.
-    -   `url` (string): The URL of the data.
-    -   `responseKey` (string): The response key of the component.
--   `exclude` (array): The data to be excluded.
--   `type` (string): The type of the component.
-
-### Example
-
-```json
-        {
-            "id": "mmtrbc_tsne",
-            "type": "Plotly",
-            "col": 2,
-            "rowspan": 3,
-            "settings": {
-                "preset": "mmtrbc",
-                "ignoreEmptyData": true
-            },
-            "parser": {
-                "sources": [{
-                    "name": "metadata",
-                    "url": "<your-backend-url>"
-                }, {
-                    "name": "gene",
-                    "url": "<your-backend-url>",
-                    "responseKey": "gene"
-                }],
-                "exclude": ["BC-Mes", "BC-NE", "BC-Im"],
-                "type": "scatter"
-            }
-        }
-```
+# Plotly Component
+
+The Plotly component integrates Plotly.js for advanced interactive visualizations. It supports scatter plots, violin plots, and other Plotly chart types with dynamic data fetching from backend APIs. Plotly provides additional interactivity like zoom, pan, hover tooltips, and data selection that complement the ECharts-based visualizations.
+
+> **Note:** This component requires a backend API to supply data. A live demo is not available in this documentation.
+
+## How It Works
+
+The Plotly component uses a parser-based data pipeline. It fetches data from one or more backend sources, transforms the responses based on the configured parser type, and renders the result as an interactive Plotly chart.
+
+```
+ +-----------+      +------------+      +-----------+      +----------------+
+ |  Backend  | ---> |   Parser   | ---> |  Plotly   | ---> |  Interactive   |
+ |  API(s)   |      | (transform)|      |  Render   |      |  Chart Output  |
+ +-----------+      +------------+      +-----------+      +----------------+
+       |                  |
+       |   sources[]      |   type: "scatter" | "violin" | ...
+       |   responseKey    |   exclude: [...]
+       +------------------+
+
+ Trigger (optional)
+ +------------+      Listens for events from other components
+ |  Event     | ---> to refresh or filter the chart dynamically
+ +------------+
+```
+
+When multiple sources are defined, the parser merges them before rendering. For example, a scatter plot may combine cell metadata (coordinates, cell types) with gene expression values (color overlay).
+
+## Properties
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `type` | string | Yes | Must be set to `"Plotly"`. |
+| `id` | string | Yes | A unique identifier for this component instance. Used for cross-component references and event targeting. |
+| `row` | int | No | The grid row position where the component is placed (1-based). |
+| `col` | int | No | The grid column position where the component is placed (1-based). |
+| `rowspan` | int | No | The number of grid rows this component spans. Defaults to 1. |
+| `colspan` | int | No | The number of grid columns this component spans. Defaults to 1. |
+| `settings` | object | No | Display and behavior settings. See the **Settings** table below. |
+| `parser` | object | Yes | Defines data sources, transformations, and chart type. See the **Parser** table below. |
+| `trigger` | object | No | Configures event listeners so this component reacts to changes in other components (e.g., gene selection). |
+
+### Settings
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `preset` | string | - | A named preset that applies predefined styling and layout options (e.g., `"mmtrbc"`). |
+| `ignoreEmptyData` | boolean | `false` | When `true`, the component will not render an error or placeholder if the API returns empty data. |
+
+### Parser
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `sources` | array | Yes | An array of data source objects. Each source defines a backend endpoint to fetch data from. |
+| `sources[].name` | string | Yes | A label identifying this data source (e.g., `"metadata"`, `"gene"`). Used internally for data merging. |
+| `sources[].url` | string | Yes | The backend URL that returns the data for this source. |
+| `sources[].responseKey` | string | No | A dot-path key to extract a specific field from the API response. For example, `"gene"` extracts `response.gene`. |
+| `exclude` | array | No | An array of category names to exclude from the rendered chart. Useful for filtering out unwanted groups. |
+| `type` | string | Yes | The Plotly chart type to render. Supported values include `"scatter"` and `"violin"`. |
+
+## Example
+
+### Scatter Plot (t-SNE / UMAP)
+
+```json
+{
+    "id": "mmtrbc_tsne",
+    "type": "Plotly",
+    "col": 2,
+    "rowspan": 3,
+    "settings": {
+        "preset": "mmtrbc",
+        "ignoreEmptyData": true
+    },
+    "parser": {
+        "sources": [
+            {
+                // Cell-type metadata with x/y coordinates
+                "name": "metadata",
+                "url": "<your-backend-url>/api/metadata"
+            },
+            {
+                // Gene expression values overlaid as color
+                "name": "gene",
+                "url": "<your-backend-url>/api/gene",
+                "responseKey": "gene"
+            }
+        ],
+        // Exclude specific cell-type categories from the plot
+        "exclude": ["BC-Mes", "BC-NE", "BC-Im"],
+        "type": "scatter"
+    }
+}
+```
+
+### Violin Plot
+
+```json
+{
+    "id": "mmtrbc_violin",
+    "type": "Plotly",
+    "col": 1,
+    "rowspan": 3,
+    "settings": {
+        "preset": "mmtrbc",
+        "ignoreEmptyData": true
+    },
+    "parser": {
+        "sources": [
+            {
+                "name": "metadata",
+                "url": "<your-backend-url>/api/metadata"
+            },
+            {
+                "name": "gene",
+                "url": "<your-backend-url>/api/gene",
+                "responseKey": "gene"
+            }
+        ],
+        "exclude": ["BC-Mes", "BC-NE"],
+        // Renders a violin plot showing expression distribution per cell type
+        "type": "violin"
+    }
+}
+```
+
+## See Also
+
+- [DotBio Component](/components/dotBio.md) - Dot plot for gene expression across cell types
+- [Echart Component](/components/echart.md) - General-purpose chart component using ECharts
+- [Configuration](/configuration.md) - How to set up page mode
+- [MmTrBC Showcase](https://visualify.pharmacy.arizona.edu/MmTrBC/) - Live project using Plotly scatter and violin plots