visualifyjs 2.5.3-2.dev → 3.0.0

package/docs/docs/_404.md

@@ -1,52 +1,52 @@
-<style>
-    body {
-      font-family: Arial, sans-serif;
-      display: flex;
-      justify-content: center;
-      align-items: center;
-      height: 100vh;
-      margin: 0;
-    }
-    
-    .container {
-      text-align: center;
-      background-color: #ffffff;
-      padding: 50px;
-      margin-top: 5vh;
-      border-radius: 10px;
-      box-shadow: 0px 0px 10px rgba(0, 0, 0, 0.1);
-    }
-    
-    .container h1 {
-      font-size: 72px;
-      margin-bottom: 20px;
-      color: #ff5252;
-    }
-    
-    .container p {
-      font-size: 24px;
-      margin-bottom: 30px;
-    }
-    
-    .container a {
-      font-size: 18px;
-      text-decoration: none;
-      color: #2196f3;
-      border: 1px solid #2196f3;
-      padding: 10px 15px;
-      border-radius: 5px;
-      transition: background-color 0.3s, color 0.3s;
-    }
-    
-    .container a:hover {
-      background-color: #2196f3;
-      color: #ffffff;
-    }
-
-</style>
-
-<div class="container">
-    <h1>404</h1>
-    <p>Oops! The page you're looking for doesn't exist.</p>
-    <a href="/">Go Home</a>
+<style>
+    body {
+      font-family: Arial, sans-serif;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      height: 100vh;
+      margin: 0;
+    }
+    
+    .container {
+      text-align: center;
+      background-color: #ffffff;
+      padding: 50px;
+      margin-top: 5vh;
+      border-radius: 10px;
+      box-shadow: 0px 0px 10px rgba(0, 0, 0, 0.1);
+    }
+    
+    .container h1 {
+      font-size: 72px;
+      margin-bottom: 20px;
+      color: #ff5252;
+    }
+    
+    .container p {
+      font-size: 24px;
+      margin-bottom: 30px;
+    }
+    
+    .container a {
+      font-size: 18px;
+      text-decoration: none;
+      color: #2196f3;
+      border: 1px solid #2196f3;
+      padding: 10px 15px;
+      border-radius: 5px;
+      transition: background-color 0.3s, color 0.3s;
+    }
+    
+    .container a:hover {
+      background-color: #2196f3;
+      color: #ffffff;
+    }
+
+</style>
+
+<div class="container">
+    <h1>404</h1>
+    <p>Oops! The page you're looking for doesn't exist.</p>
+    <a href="/">Go Home</a>
 </div>

package/docs/docs/_coverpage.md

@@ -1,11 +1,11 @@
-<!-- _coverpage.md -->
-
-![logo](./static/logo/logo_256x256.png)
-
-# visualify.js <small>2.5.3</small>
-
-> A magical data portal generator
-
-[GitHub](https://github.com/visualify)
-[Getting Started](#visualify)
-
+<!-- _coverpage.md -->
+
+![logo](./static/logo/logo_256x256.png)
+
+# visualify.js <small>3.0.0</small>
+
+> A magical data portal generator
+
+[GitHub](https://github.com/visualify)
+[Getting Started](#visualify)
+

package/docs/docs/_sidebar.md

@@ -1,44 +1,54 @@
--   Getting started
-
-    -   [Introduction](/README.md)
-    -   [Quick start](/quickstart.md)
-    -   [More pages](/more-pages.md)
-
--   Visualify.Recharts
-    
-    -   [Usage](/rechart-basic-usage.md)
-    -   [Attributes](/rechart-attributes.md)
-    -   [Line Chart](/Rechart/line.md)
-    -   [Bar Chart](/Rechart/bar.md)
-    -   [Pie Chart](/Rechart/pie.md)
-    -   [Radar Chart](/Rechart/radar.md)
-    -   [Funnel Chart](/Rechart/funnel.md)
-    -   [Scatter Chart](/Rechart/scatter.md)
-    
-  
--   Page Mode
-
-    -   [ScatterL](/components/scatterL.md)
-    -   [Visium](/components/visium.md)
-    -   [DotBio](/components/dotBio.md)
-    -   [Echart](/components/echart.md)
-    -   [Plotly](/components/plotly.md)
-    -   [Macaron](/components/macaron.md)
-    -   [More...](/components/more.md)
-
--   Customization
-
-    -   [Configuration](/configuration.md)
-    -   [Theme](/theme.md)
-
--   Guide
-
-    -   [CLI](/CLI.md)
-    -   [Deploy](/deploy.md)
-
--   Showcase
-
-    -   [MmTrBC](https://visualify.pharmacy.arizona.edu/MmTrBC/)
-    -   [EsoDev](https://visualify.pharmacy.arizona.edu/EsoDev/)
-
--   [UpdateLog](/log.md)
+-   Getting Started
+
+    -   [Introduction](/README.md)
+    -   [Quick Start](/quickstart.md)
+    -   [Docsify Plugin](/docsify-plugin.md)
+
+-   Charts (2D)
+
+    -   [Usage](/rechart-basic-usage.md)
+    -   [Attributes](/rechart-attributes.md)
+    -   [Line Chart](/Rechart/line.md)
+    -   [Bar Chart](/Rechart/bar.md)
+    -   [Pie Chart](/Rechart/pie.md)
+    -   [Radar Chart](/Rechart/radar.md)
+    -   [Funnel Chart](/Rechart/funnel.md)
+    -   [Scatter Chart](/Rechart/scatter.md)
+
+-   Charts (3D)
+
+    -   [3D Visualization](/3d-visualization.md)
+
+-   Page Mode
+
+    -   [ScatterL](/components/scatterL.md)
+    -   [Visium](/components/visium.md)
+    -   [DotBio](/components/dotBio.md)
+    -   [Echart](/components/echart.md)
+    -   [Plotly](/components/plotly.md)
+    -   [Macaron](/components/macaron.md)
+    -   [More...](/components/more.md)
+
+-   Customization
+
+    -   [Configuration](/configuration.md)
+    -   [Theme](/theme.md)
+
+-   Developer Experience
+
+    -   [Hot Module Replacement](/hmr.md)
+    -   [TypeScript](/typescript.md)
+    -   [Visual Editor](/visual-editor.md)
+    -   [Internationalization](/i18n.md)
+
+-   Guide
+
+    -   [CLI](/CLI.md)
+    -   [Deploy](/deploy.md)
+
+-   Showcase
+
+    -   [MmTrBC](https://visualify.pharmacy.arizona.edu/MmTrBC/)
+    -   [EsoDev](https://visualify.pharmacy.arizona.edu/EsoDev/)
+
+-   [UpdateLog](/log.md)

package/docs/docs/components/dotBio.md

@@ -1,34 +1,87 @@
-# DotBio Component
-
-The DotBio component is a dot plot that
-displays the expression of genes in different cell types. 
-
-
-## Properties
-
-The DotBio component has the following properties:
-
--   `type` (string): The type of the component, in this case `DotBio`.
--   `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.
--   `meta` (object): The metadata API of the component.
-    -   `name` (string): The name of the metadata.
-    -   `url` (string): The URL of the metadata.
--   `exclude_celltype` (array): The cell types to be excluded.
--   `gene` (string): The gene API.
--   `genelist` (string): The genelist variable name we want to use.
-
-### 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.
--   `showscale` (boolean): Whether to show the scale or not.
--   `showlegend` (boolean): Whether to show the legend or not.
-        
-
+# DotBio Component
+
+The DotBio component creates dot plots (also known as bubble plots) commonly used in bioinformatics to display gene expression patterns across cell types. Each dot represents the expression of a gene in a specific cell type, with size indicating the percentage of expressing cells and color indicating expression level.
+
+> **Note:** This component requires a backend API to supply gene expression and metadata. A live demo is not available in this documentation.
+
+## How It Works
+
+The DotBio component fetches cell-type metadata and gene expression data from backend APIs, then renders a matrix of dots where rows are cell types and columns are genes.
+
+```
+              Gene A   Gene B   Gene C   Gene D
+Cell Type 1    ●        ◉        ○        ●
+Cell Type 2    ○        ●        ◉        ○
+Cell Type 3    ◉        ○        ●        ◉
+Cell Type 4    ●        ●        ○        ○
+
+● = high expression (large, dark)
+◉ = medium expression
+○ = low expression (small, light)
+```
+
+The dot size encodes the percentage of cells expressing the gene, while the dot color encodes the average expression level. This dual encoding lets researchers quickly identify which genes are active in which cell populations.
+
+## Properties
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `type` | string | Yes | Must be set to `"DotBio"`. |
+| `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. |
+| `meta` | object | Yes | Defines the metadata API endpoint that provides cell-type information. |
+| `meta.name` | string | Yes | A label for the metadata source (e.g., `"metadata"`). |
+| `meta.url` | string | Yes | The backend URL that returns cell-type metadata. |
+| `exclude_celltype` | array | No | An array of cell-type names to exclude from the plot. Useful for filtering out irrelevant or noisy populations. |
+| `gene` | string | Yes | The backend API URL that returns gene expression data for the selected genes. |
+| `genelist` | string | Yes | The name of the gene list variable to use. This should match a gene list defined elsewhere in the page configuration. |
+
+### 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. |
+| `showscale` | boolean | `true` | Whether to display the color scale legend alongside the plot. |
+| `showlegend` | boolean | `true` | Whether to display the size legend indicating percentage of expressing cells. |
+
+## Example
+
+```json
+{
+    "id": "dotbio_expression",
+    "type": "DotBio",
+    "col": 1,
+    "rowspan": 4,
+    "colspan": 2,
+    "settings": {
+        "preset": "mmtrbc",
+        "ignoreEmptyData": true,
+        "showscale": true,
+        "showlegend": true
+    },
+    "meta": {
+        // Label for this metadata source
+        "name": "metadata",
+        // Backend endpoint returning cell-type information
+        "url": "<your-backend-url>/api/metadata"
+    },
+    // Cell types to exclude from the visualization
+    "exclude_celltype": ["BC-Mes", "BC-NE"],
+    // Backend endpoint returning gene expression values
+    "gene": "<your-backend-url>/api/gene",
+    // References a gene list defined in the page configuration
+    "genelist": "selected_genes"
+}
+```
+
+## See Also
+
+- [Plotly Component](/components/plotly.md) - For scatter and violin plots of expression data
+- [Echart Component](/components/echart.md) - General-purpose chart component
+- [Configuration](/configuration.md) - How to set up page mode
+- [MmTrBC Showcase](https://visualify.pharmacy.arizona.edu/MmTrBC/) - Live project using DotBio and other components

package/docs/docs/components/echart.md

@@ -1,82 +1,171 @@
-# Echart Component
-
-The Echart component is a wrapper around the
-[Apache ECharts](https://echarts.apache.org/en/index.html) library. It is used
-to create a variety of visualizations including scatter plots, line charts, bar
-charts, and more.
-
-This Echart Component is same as the Rechart Component, but it is used for the
-page mode, which enable the user to create a page with multiple components. And
-it also **support the API to fetch the data**.
-
-## Properties
-
-The Echart component has the following properties:
-
--   `type` (string): The type of the component, in this case `Echart`.
--   `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.
--   `config` (object): The configuration of the component.
--   `parser` (object): The parser of the component.
--   `trigger` (object): The trigger of the component.
-
-### config Properties
-
-The `config` object has the following properties:
-
--   `width` (int): The width of the component.
--   `height` (int): The height of the component.
--   `preset` (string): The preset of the component.
--   `title` (string): The title of the component.
--   `xAxis` (string): The x-axis of the component.
--   `yAxis` (string): The y-axis of the component.
--   `legend` (string): The legend of the component.
--   `tooltip` (string): The tooltip of the component.
--   `data` (string): The data of the component.
-
-### 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.
-    -   `type` (string): The type of the component.
-    -   `responseKey` (string): The response key of the component.
-    -   `trigger` (object): The trigger of the component.
-        -   `title` (boolean): set the title to the triiger value.
-
-### Example
-
-```json
-        {
-            "id": "mmtrbc_tsne",
-            "type": "Echart",
-            "col": 2,
-            "rowspan": 3,
-            "config": {
-                "width": 600,
-                "height": 600,
-                "preset": "mmtrbc",
-                "title": " "
-            },
-            "parser": {
-                "sources": [{
-                    "name": "metadata",
-                    "url": "<your-backend-url>"
-                }, {
-                    "name": "gene",
-                    "url": "<your-backend-url>",
-                    "responseKey": "gene",
-                    "trigger": {
-                        "name": "mmtrbc_gene",
-                        "title": true
-                    }
-                }],
-                "type": "scatter"
-            }
-        }
-```
+# Echart Component
+
+The Echart component is a wrapper around the [Apache ECharts](https://echarts.apache.org/en/index.html) library. It provides the same charting capabilities as [Charts (2D)](/rechart-basic-usage.md) but is designed for **page mode**, enabling multi-component layouts with API data fetching.
+
+## Live Demo
+
+The Echart component uses the same rendering engine as the standard charts. Here's a scatter plot example:
+
+```visualify
+{
+    "type": "scatter",
+    "title": "Gene Expression Scatter Plot",
+    "data": {
+        "categories": [],
+        "series": [
+            {
+                "name": "Cluster A",
+                "data": [[10.0, 8.04], [8.0, 6.95], [13.0, 7.58], [9.0, 8.81], [11.0, 8.33], [14.0, 9.96], [6.0, 7.24], [4.0, 4.26], [12.0, 10.84], [7.0, 4.82], [5.0, 5.68]]
+            },
+            {
+                "name": "Cluster B",
+                "data": [[8.0, 3.04], [8.0, 3.95], [8.0, 4.58], [8.0, 3.81], [8.0, 4.33], [8.0, 3.96], [8.0, 4.24], [19.0, 12.5], [8.0, 3.26], [8.0, 3.84], [8.0, 3.68]]
+            }
+        ]
+    }
+}
+```
+
+And a line chart with multiple series:
+
+```visualify
+{
+    "type": "line",
+    "title": "Time-Series Expression Data",
+    "smooth": true,
+    "data": {
+        "categories": ["0h", "2h", "4h", "8h", "12h", "24h", "48h"],
+        "series": [
+            { "name": "Gene A", "data": [2.1, 3.5, 5.2, 8.1, 6.3, 4.2, 3.0] },
+            { "name": "Gene B", "data": [1.0, 1.2, 2.8, 7.5, 12.1, 9.8, 5.4] },
+            { "name": "Gene C", "data": [5.5, 5.0, 4.2, 3.1, 2.5, 2.0, 1.8] }
+        ]
+    },
+    "yAxis": { "name": "Expression Level" }
+}
+```
+
+## How It Works
+
+In page mode, the Echart component connects to **backend APIs** to fetch data dynamically. The data flow is:
+
+```
+┌─────────────┐     ┌─────────────┐     ┌──────────────┐
+│  visualify   │────>│   Parser    │────>│   ECharts    │
+│   .json      │     │  (fetch +   │     │  (render)    │
+│  config      │     │   transform)│     │              │
+└─────────────┘     └─────────────┘     └──────────────┘
+       │                    │
+       │  parser.sources    │  fetched_data
+       v                    v
+┌─────────────┐     ┌─────────────┐
+│  Backend    │────>│  Data       │
+│  API        │     │  Transform  │
+└─────────────┘     └─────────────┘
+```
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | string | Yes | Must be `"Echart"` |
+| `id` | string | Yes | Unique identifier for the component |
+| `row` | int | No | Grid row position |
+| `col` | int | No | Grid column position |
+| `rowspan` | int | No | Number of rows to span |
+| `colspan` | int | No | Number of columns to span |
+| `config` | object | Yes | Chart configuration (see below) |
+| `parser` | object | No | Data fetching configuration |
+| `trigger` | object | No | Event trigger configuration |
+
+### config Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `width` | int | Chart width in pixels |
+| `height` | int | Chart height in pixels |
+| `preset` | string | Named preset configuration |
+| `title` | string | Chart title |
+| `xAxis` | string/array | X-axis configuration |
+| `yAxis` | string/array | Y-axis configuration |
+| `legend` | object | Legend configuration |
+| `tooltip` | object | Tooltip configuration |
+| `data` | object | Inline data (when not using parser) |
+
+### parser Properties
+
+The `parser` object configures dynamic data fetching:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `sources` | array | Array of data source configurations |
+| `sources[].name` | string | Source identifier |
+| `sources[].url` | string | Backend API URL |
+| `sources[].type` | string | Chart type (e.g., `"scatter"`) |
+| `sources[].responseKey` | string | Key to extract from API response |
+| `sources[].trigger` | object | Trigger configuration for interactivity |
+| `sources[].trigger.name` | string | Trigger name (links to other components) |
+| `sources[].trigger.title` | boolean | Whether to update the chart title |
+
+## Example
+
+### Page Mode with API Data
+
+```json
+{
+    "id": "expression_tsne",
+    "type": "Echart",
+    "col": 2,
+    "rowspan": 3,
+    "config": {
+        "width": 600,
+        "height": 600,
+        "preset": "mmtrbc",
+        "title": "t-SNE Visualization"
+    },
+    "parser": {
+        "sources": [
+            {
+                "name": "metadata",
+                "url": "https://your-api.com/metadata"
+            },
+            {
+                "name": "gene",
+                "url": "https://your-api.com/gene",
+                "responseKey": "gene",
+                "trigger": {
+                    "name": "gene_search",
+                    "title": true
+                }
+            }
+        ],
+        "type": "scatter"
+    }
+}
+```
+
+### Static Data (No API)
+
+```json
+{
+    "id": "static_chart",
+    "type": "Echart",
+    "row": 1,
+    "col": 1,
+    "config": {
+        "title": "Static Bar Chart",
+        "type": "bar",
+        "data": {
+            "Series A": [120, 200, 150, 80, 70],
+            "Series B": [60, 120, 90, 140, 130]
+        },
+        "xAxis": ["Mon", "Tue", "Wed", "Thu", "Fri"]
+    }
+}
+```
+
+## See Also
+
+- [Charts (2D)](/rechart-basic-usage.md) - Same engine, simpler usage for standalone charts
+- [Configuration](/configuration.md) - How to set up page mode
+- [MmTrBC Showcase](https://visualify.pharmacy.arizona.edu/MmTrBC/) - Live example using Echart components