visualifyjs 2.5.3 → 3.0.0

package/docs/docs/components/macaron.md

@@ -1,145 +1,156 @@
-# Macaron Component
-
-The Macaron component is used to display a macaron plot for relation of nodes on
-the page.
-
-The Macaron component also has interactive features, such as the ability to drag
-and drop nodes, and the ability to select nodes.
-
-## Properties
-
-The Macaron component has the following properties:
-
--   `type` (string): The type of the component, in this case `Macaron`.
--   `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.
--   `data` (object): The data of the component.
-
-### config Properties
-
-The `config` object has the following properties:
-
--   `animation` (boolean): Whether to animate the component or not.
--   `draggable` (boolean): Whether to make the component draggable or not.
--   `height` (int): The height of the component.
--   `unclickable` (array): The nodes that are unclickable.
--   `symbolSize` (string): The size of the symbols in the component.
--   `color` (object): The color of the component.
-    -   `selected` (string): The color of the selected nodes.
-    -   `unselectable` (string): The color of the unselectable nodes.
-
-### data Properties
-
-The `data` object has the following properties:
-
--   `nodes` (array): The nodes of the component.
-    -   `name` (string): The name of the node.
-    -   `category` (int): The category of the node.
-    -   `value` (int): The value of the node.
--   `edges` (array): The edges of the component.
--   `categories` (array): The categories of the component.
-
-### Example
-
-```json
-{
-            "id": "celltype",
-            "type": "Macaron",
-            "title": "Select Cell Type",
-            "style": {
-                "height": "350px",
-                "width": "350px",
-                "font": "Arial, sans-serif",
-                "border": ""
-            },
-            "data": {
-                "nodes": [{
-                        "name": "Esophagus",
-                        "category": 1,
-                        "value": 216229
-                    },
-                    {
-                        "name": "Epithelium",
-                        "category": 2,
-                        "value": 108800
-                    },
-                    {
-                        "name": "Stroma",
-                        "category": 2,
-                        "value": 107429
-                    },
-                    {
-                        "name": "EPI (E)",
-                        "category": 3,
-                        "value": 97799
-                    },
-                    {
-                        "name": "ST (E)",
-                        "category": 3,
-                        "value": 1760
-                    }
-                ],
-                "edges": [{
-                        "source": "Esophagus",
-                        "target": "Epithelium",
-                        "level": 1
-                    },
-                    {
-                        "source": "Esophagus",
-                        "target": "Stroma",
-                        "level": 1
-                    },
-                    {
-                        "source": "Epithelium",
-                        "target": "IM (E)",
-                        "level": 2
-                    },
-                    {
-                        "source": "Epithelium",
-                        "target": "ERY (E)",
-                        "level": 2
-                    },
-                    {
-                        "source": "Stroma",
-                        "target": "MES (S)",
-                        "level": 2
-                    },
-                    {
-                        "source": "Stroma",
-                        "target": "ENS (S)",
-                        "level": 2
-                    },
-                    {
-                        "source": "Stroma",
-                        "target": "ENDO (S)",
-                        "level": 2
-                    }
-                ],
-                "categories": [{
-                        "name": "Category 1"
-                    },
-                    {
-                        "name": "Category 2"
-                    },
-                    {
-                        "name": "Category 3"
-                    }
-                ]
-            },
-            "config": {
-                "animation": false,
-                "draggable": true,
-                "height": "88%",
-                "unclickable": ["EPI (S)", "Esophagus"],
-                "symbolSize": "value",
-                "color": {
-                    "selected": "skyblue",
-                    "unselectable": "black"
-                }
-            },
-            "row": 1,
-            "col": 1
-        }
-```
+# Macaron Component
+
+The Macaron component renders an interactive **graph visualization** showing relationships between nodes. It's ideal for displaying hierarchical data, network graphs, and taxonomy trees with drag-and-drop interactivity.
+
+## Features
+
+- Interactive node selection with click events
+- Drag-and-drop repositioning of nodes
+- Configurable node sizes based on data values
+- Category-based coloring
+- Hierarchical edge relationships
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│              Macaron Graph               │
+│                                          │
+│    ┌───────┐                             │
+│    │ Root  │──────────┐                  │
+│    │ Node  │          │                  │
+│    └───┬───┘     ┌────┴────┐             │
+│        │         │ Child B │             │
+│   ┌────┴────┐    └────┬────┘             │
+│   │ Child A │         │                  │
+│   └────┬────┘    ┌────┴────┐             │
+│        │         │ Leaf D  │             │
+│   ┌────┴────┐    └─────────┘             │
+│   │ Leaf C  │                            │
+│   └─────────┘                            │
+│                                          │
+│  Nodes: sized by value, colored by       │
+│  category, draggable, selectable         │
+└─────────────────────────────────────────┘
+```
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | string | Yes | Must be `"Macaron"` |
+| `id` | string | Yes | Unique identifier for the component |
+| `title` | string | No | Title displayed above the graph |
+| `row` | int | No | Grid row position |
+| `col` | int | No | Grid column position |
+| `style` | object | No | CSS styles (height, width, font, border) |
+| `config` | object | Yes | Graph configuration (see below) |
+| `data` | object | Yes | Graph data: nodes, edges, categories |
+
+### config Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `animation` | boolean | `true` | Enable/disable animation |
+| `draggable` | boolean | `false` | Allow drag-and-drop of nodes |
+| `height` | string | `"100%"` | Graph height |
+| `unclickable` | array | `[]` | Node names that cannot be clicked |
+| `symbolSize` | string | `"value"` | Size basis: `"value"` for data-driven |
+| `color.selected` | string | - | Color for selected nodes |
+| `color.unselectable` | string | - | Color for unclickable nodes |
+
+### data Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `nodes` | array | Array of `{ name, category, value }` objects |
+| `edges` | array | Array of `{ source, target, level }` objects |
+| `categories` | array | Array of `{ name }` objects for node coloring |
+
+## Example
+
+### Cell Type Hierarchy
+
+This example shows a biological cell type taxonomy tree:
+
+```json
+{
+    "id": "celltype",
+    "type": "Macaron",
+    "title": "Select Cell Type",
+    "row": 1,
+    "col": 1,
+    "style": {
+        "height": "350px",
+        "width": "350px"
+    },
+    "data": {
+        "nodes": [
+            { "name": "Esophagus", "category": 1, "value": 216229 },
+            { "name": "Epithelium", "category": 2, "value": 108800 },
+            { "name": "Stroma", "category": 2, "value": 107429 },
+            { "name": "EPI (E)", "category": 3, "value": 97799 },
+            { "name": "ST (E)", "category": 3, "value": 1760 },
+            { "name": "IM (E)", "category": 3, "value": 5200 },
+            { "name": "MES (S)", "category": 3, "value": 45000 },
+            { "name": "ENS (S)", "category": 3, "value": 32000 },
+            { "name": "ENDO (S)", "category": 3, "value": 30429 }
+        ],
+        "edges": [
+            { "source": "Esophagus", "target": "Epithelium", "level": 1 },
+            { "source": "Esophagus", "target": "Stroma", "level": 1 },
+            { "source": "Epithelium", "target": "EPI (E)", "level": 2 },
+            { "source": "Epithelium", "target": "ST (E)", "level": 2 },
+            { "source": "Epithelium", "target": "IM (E)", "level": 2 },
+            { "source": "Stroma", "target": "MES (S)", "level": 2 },
+            { "source": "Stroma", "target": "ENS (S)", "level": 2 },
+            { "source": "Stroma", "target": "ENDO (S)", "level": 2 }
+        ],
+        "categories": [
+            { "name": "Root" },
+            { "name": "Tissue" },
+            { "name": "Cell Type" }
+        ]
+    },
+    "config": {
+        "animation": false,
+        "draggable": true,
+        "height": "88%",
+        "unclickable": ["Esophagus"],
+        "symbolSize": "value",
+        "color": {
+            "selected": "skyblue",
+            "unselectable": "black"
+        }
+    }
+}
+```
+
+### How Selection Works
+
+When a user clicks a node in the Macaron graph:
+
+1. The node becomes **highlighted** with the `selected` color
+2. The selection is stored in the global state under the component's `id`
+3. Other components (e.g., Echart, ScatterL) can **trigger** on this selection to update their data
+4. `unclickable` nodes are displayed with the `unselectable` color and do not respond to clicks
+
+This creates an interactive filtering workflow:
+
+```
+User clicks "EPI (E)" in Macaron
+        │
+        v
+Global state: celltype = "EPI (E)"
+        │
+        v
+Echart component triggers API call with "EPI (E)"
+        │
+        v
+Scatter plot updates to show only EPI cells
+```
+
+## See Also
+
+- [EsoDev Showcase](https://visualify.pharmacy.arizona.edu/EsoDev/) - Live example with Macaron cell type selector
+- [Configuration](/configuration.md) - Page mode setup

package/docs/docs/components/markdown.md

@@ -0,0 +1,42 @@
+# Markdown Component
+
+The Markdown component renders Markdown content within a page mode layout. Use it for text-heavy content like descriptions, documentation, or README-style content alongside visualizations.
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `type` | string | Yes | Must be `"Markdown"`. |
+| `id` | string | No | Unique identifier for the component. |
+| `row` | int | Yes | The row in which the component is displayed. |
+| `col` | int | Yes | The column in which the component is displayed. |
+| `content` | string | No | Inline Markdown string to render. Use this for short content. |
+| `src` | string | No | Path or URL to a Markdown file to load and render. Use this for longer content. |
+
+> **Note:** Provide either `content` or `src`, not both. If both are specified, `content` takes precedence.
+
+## Example
+
+### Inline Content
+
+```json
+{
+    "type": "Markdown",
+    "id": "description",
+    "row": 1,
+    "col": 1,
+    "content": "## About This Dataset\n\nThis dataset contains gene expression profiles across **12 tissue types**.\n\n- Source: GEO Database\n- Samples: 240\n- Platform: RNA-seq"
+}
+```
+
+### Loading from a File
+
+```json
+{
+    "type": "Markdown",
+    "id": "readme",
+    "row": 1,
+    "col": 1,
+    "src": "./data/description.md"
+}
+```