visualifyjs 2.5.3-2.dev → 3.0.0

package/docs/CHANGELOG.md

@@ -0,0 +1,148 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.0] - 2026-02-20
+
+### Fixed
+
+- **Bundle externalization** — echarts and plotly.js are now externalized from legacy IIFE builds, reducing bundle from 9.6 MB to 2.8 MB. Three.js remains bundled (eagerly imported).
+- **CDN dependency warnings** — visualify.js now warns in console if echarts or plotly CDN scripts are missing, with instructions on what to add.
+- **Docs site cleanup** — removed unnecessary Three.js CDN and ReactThree stubs from docs/index.html (now bundled).
+- **Loader update** — `visualify-loader.js` no longer auto-loads Three.js CDN (bundled with main script).
+- **Dot plot rendering** — RePlotly now respects `props.data` passed directly from parent components (e.g., DotBio), fixing MmTrBC dot plots that stopped rendering.
+- **Console noise cleanup** — removed debug `console.log` statements from production output (echartswitcher, selection, scatter components).
+
+### Improved
+
+- **Selection component UI** — redesigned react-select dropdown with pill-shaped tags, refined theme colors, smooth hover/focus transitions, and cleaner indicator styles.
+- **Timeline component UI** — redesigned with card-like node containers, hollow animated dots, gradient connector line, chip-style sub-item buttons, active node highlighting, and custom scrollbar.
+- **Beta channel** — development builds available directly from the `dev` branch via CDN or `npm install github:visualify/visualify.js#dev`.
+
+### Breaking Changes
+
+- **CLI merged into core package** - The `@visualify/cli` package is now deprecated and merged into the main `visualifyjs` package. Users should uninstall `@visualify/cli` and install `visualifyjs` globally instead.
+- **Configuration moved from `window.$visualify` to `visualify.json`** - Inline JavaScript configuration is no longer supported. Create a `visualify.json` file in your project root instead.
+- **New command structure with namespaces** - Commands have been restructured:
+  - `visualify serve` → `visualify dev`
+  - `visualify start` → `visualify dev portal`
+  - `visualify load-json` → `visualify portal load-json`
+  - `visualify mapping` → `visualify portal mapping`
+  - `visualify rtree2d` → `visualify portal rtree2d`
+- **Mode values changed** - The `mode` property values have been renamed:
+  - `mode: 'pages'` → `mode: 'portal'`
+  - `mode: 'charts'` → `mode: 'docs'`
+- **Init command requires template** - The `visualify init` command now requires a template argument: `docs`, `portal`, or `full`.
+
+### Added
+
+- **3D Visualization Support** - New 3D chart types using ECharts GL and Three.js
+  - `scatter3d` - 3D scatter plots with x, y, z dimensions
+  - `bar3d` - 3D bar charts with Lambert shading
+  - `surface3d` - 3D surface/height map visualizations
+  - `line3d` - 3D line/trajectory charts
+  - `threejs` - Custom Three.js scenes with React Three Fiber integration
+- WebGL support detection with graceful fallback for unsupported browsers
+- Lazy loading for 3D libraries (loaded on-demand to minimize bundle size)
+- Docsify plugin system for embedding charts in markdown documentation
+  - `visualify` code block support in markdown
+  - Auto-mount charts with `data-visualify` attribute
+  - SPA navigation support for single-page documentation
+- `visualify.json` configuration file support with JSON schema validation
+- Auto-detection mode for `visualify dev` command - automatically detects project type from configuration or directory structure
+- Separate entry points for `docs` and `portal` bundles for optimized builds
+- `visualify docs` namespace with `dev` and `build` subcommands
+- `visualify portal` namespace with `dev`, `build`, `load-json`, `mapping`, and `rtree2d` subcommands
+- Support for `visualify.config.js` for dynamic configuration
+- `--verbose` global flag for debug output
+- `--dry-run` option for configuration validation
+- Environment variable support (`VISUALIFY_PORT`, `VISUALIFY_HOST`, `VISUALIFY_MODE`)
+
+### Changed
+
+- Build output structure now uses separate entry points for docs and portal modes
+- Development server now defaults to auto-detection mode
+- Improved error messages with suggestions for common issues
+- Updated CLI help documentation with examples
+
+### Deprecated
+
+- `@visualify/cli` package - will not receive updates after 2026-06-01
+- `window.$visualify` inline configuration - migrate to `visualify.json`
+- Old mode values (`pages`, `charts`) - use `portal`, `docs` instead
+
+### Removed
+
+- Support for `visualify serve` command (use `visualify dev`)
+- Support for `visualify start` command (use `visualify dev portal`)
+- Direct `visualify load-json` command (use `visualify portal load-json`)
+- Direct `visualify mapping` command (use `visualify portal mapping`)
+- Direct `visualify rtree2d` command (use `visualify portal rtree2d`)
+
+### Migration Guide
+
+See the [v3.0.0 Migration Guide](./docs/migration/v3-migration.md) for detailed instructions on upgrading from v2.x.
+
+Quick migration steps:
+1. `npm uninstall -g @visualify/cli`
+2. `npm i -g visualifyjs`
+3. Create `visualify.json` with your configuration
+4. Update mode values (`pages` → `portal`, `charts` → `docs`)
+5. Update npm scripts with new command syntax
+
+---
+
+## [2.5.3] - 2024-XX-XX
+
+### Fixed
+
+- Minor bug fixes and dependency updates
+
+---
+
+## [2.5.2] - 2024-XX-XX
+
+### Changed
+
+- Dependency upgrades
+
+---
+
+## [2.5.1] - 2024-XX-XX
+
+### Fixed
+
+- Documentation updates
+
+---
+
+## [2.5.0] - 2024-XX-XX
+
+### Added
+
+- New visualization components
+- Improved theming support
+
+---
+
+## [2.0.0] - 2024-XX-XX
+
+### Added
+
+- React 18 support
+- New CLI commands
+- Enhanced chart types
+
+---
+
+## [1.0.0] - 2023-XX-XX
+
+### Added
+
+- Initial release of Visualify.js
+- Basic chart components
+- CLI tooling
+- Documentation site support

package/docs/cli/commands.md

@@ -0,0 +1,513 @@
+# CLI Command Reference
+
+Complete reference for the Visualify.js CLI commands. The CLI is included in the `visualifyjs` package (v3.0.0+).
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Global Options](#global-options)
+- [Commands](#commands)
+  - [visualify dev](#visualify-dev)
+  - [visualify init](#visualify-init)
+  - [visualify docs](#visualify-docs)
+  - [visualify portal](#visualify-portal)
+- [Exit Codes](#exit-codes)
+- [Environment Variables](#environment-variables)
+
+---
+
+## Installation
+
+```bash
+# Install globally
+npm i -g visualifyjs
+
+# Or use with npx
+npx visualifyjs dev
+```
+
+Verify installation:
+```bash
+visualify --version
+```
+
+---
+
+## Global Options
+
+These options are available for all commands:
+
+| Option | Description |
+|--------|-------------|
+| `-v, --version` | Display version number |
+| `-h, --help` | Display help for command |
+| `--verbose` | Enable verbose output for debugging |
+
+---
+
+## Commands
+
+### visualify dev
+
+Start the development server with auto-detection or explicit mode.
+
+#### Usage
+
+```bash
+visualify dev [mode] [path] [options]
+```
+
+#### Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `mode` | Development mode: `auto`, `docs`, or `portal` | `auto` |
+| `path` | Path to project directory | Current directory |
+
+#### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --port <port>` | Port to run the server | `3000` |
+| `-H, --host <host>` | Host to bind the server | `localhost` |
+| `--no-open` | Do not open browser automatically | `false` |
+
+#### Examples
+
+```bash
+# Auto-detect mode from visualify.json
+visualify dev
+
+# Explicit docs mode
+visualify dev docs
+
+# Explicit portal mode with custom port
+visualify dev portal ./my-project --port 8080
+
+# Auto-detect with specific path
+visualify dev auto ./docs --port 4000
+```
+
+#### Auto-Detection Logic
+
+When `mode` is `auto` (default), the CLI checks in order:
+
+1. `mode` property in `visualify.json`
+2. Presence of `docs/` directory → `docs` mode
+3. Presence of `portal/` directory → `portal` mode
+4. Default to `portal` mode
+
+---
+
+### visualify init
+
+Initialize a new Visualify.js project with a template.
+
+#### Usage
+
+```bash
+visualify init <template> [path] [options]
+```
+
+#### Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `template` | Template type: `docs`, `portal`, or `full` | Yes |
+| `path` | Directory to initialize | No (defaults to current) |
+
+#### Templates
+
+| Template | Description |
+|----------|-------------|
+| `docs` | Documentation site with chart support |
+| `portal` | Data portal with navigation and visualization |
+| `full` | Both docs and portal in one project |
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--force` | Overwrite existing files |
+| `--skip-install` | Skip npm install after initialization |
+
+#### Examples
+
+```bash
+# Initialize docs template in current directory
+visualify init docs
+
+# Initialize portal template in specific directory
+visualify init portal ./my-data-portal
+
+# Initialize full template with force overwrite
+visualify init full ./my-project --force
+
+# Initialize without running npm install
+visualify init docs ./docs --skip-install
+```
+
+#### Generated Structure
+
+**Docs template:**
+```
+docs/
+├── visualify.json
+├── index.html
+├── home.json
+└── .nojekyll
+```
+
+**Portal template:**
+```
+portal/
+├── visualify.json
+├── index.html
+├── home.json
+├── data/
+└── .nojekyll
+```
+
+**Full template:**
+```
+my-project/
+├── visualify.json
+├── index.html
+├── docs/
+│   └── home.json
+├── portal/
+│   └── home.json
+└── .nojekyll
+```
+
+---
+
+### visualify docs
+
+Commands for documentation mode projects.
+
+#### Subcommands
+
+##### visualify docs dev
+
+Start development server in docs mode.
+
+```bash
+visualify docs dev [path] [options]
+```
+
+Options:
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --port <port>` | Port to run the server | `3000` |
+| `-H, --host <host>` | Host to bind the server | `localhost` |
+| `--no-open` | Do not open browser | `false` |
+
+Example:
+```bash
+visualify docs dev ./docs --port 8080
+```
+
+##### visualify docs build
+
+Build the documentation for production.
+
+```bash
+visualify docs build [path] [options]
+```
+
+Options:
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-o, --output <dir>` | Output directory | `dist` |
+| `--minify` | Minify output | `true` |
+
+Example:
+```bash
+visualify docs build ./docs --output ./build
+```
+
+---
+
+### visualify portal
+
+Commands for portal mode projects and data management.
+
+#### Subcommands
+
+##### visualify portal dev
+
+Start development server in portal mode.
+
+```bash
+visualify portal dev [path] [options]
+```
+
+Options:
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --port <port>` | Port to run the server | `3000` |
+| `-H, --host <host>` | Host to bind the server | `localhost` |
+| `--no-open` | Do not open browser | `false` |
+
+Example:
+```bash
+visualify portal dev ./portal --port 8080
+```
+
+##### visualify portal build
+
+Build the portal for production.
+
+```bash
+visualify portal build [path] [options]
+```
+
+Options:
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-o, --output <dir>` | Output directory | `dist` |
+| `--minify` | Minify output | `true` |
+
+Example:
+```bash
+visualify portal build ./portal --output ./build
+```
+
+##### visualify portal load-json
+
+Load points from a JSON file into the portal data store.
+
+```bash
+visualify portal load-json <path> [options]
+```
+
+Arguments:
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `path` | Path to JSON file | Yes |
+
+Options:
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-o, --output <path>` | Output file path | Auto-generated |
+| `-f, --format <format>` | Output format: `json`, `csv` | `json` |
+
+Example:
+```bash
+# Load JSON file
+visualify portal load-json ./data/points.json
+
+# Load with custom output
+visualify portal load-json ./data/points.json --output ./processed/data.json
+```
+
+##### visualify portal mapping
+
+Create a mapping file with optional key specification.
+
+```bash
+visualify portal mapping [options] <path>
+```
+
+Arguments:
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `path` | Path to source file | Yes |
+
+Options:
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-k, --key <key>` | Key column name | `id` |
+| `-o, --output <path>` | Output file path | `mapping.json` |
+| `-s, --separator <char>` | CSV separator | `,` |
+
+Example:
+```bash
+# Create mapping with default key
+visualify portal mapping ./data/mapping.csv
+
+# Create mapping with custom key
+visualify portal mapping --key gene_id ./data/genes.csv --output ./gene-mapping.json
+```
+
+##### visualify portal rtree2d
+
+Create a 2D R-tree index for efficient spatial data searching.
+
+```bash
+visualify portal rtree2d [options] <path>
+```
+
+Arguments:
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `path` | Path to spatial data file | Yes |
+
+Options:
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-o, --output <path>` | Output directory | `./rtree` |
+| `-x, --x-field <field>` | X coordinate field name | `x` |
+| `-y, --y-field <field>` | Y coordinate field name | `y` |
+| `-i, --id-field <field>` | ID field name | `id` |
+| `--max-entries <number>` | Maximum entries per node | `9` |
+
+Example:
+```bash
+# Create R-tree with defaults
+visualify portal rtree2d ./data/spatial.json
+
+# Create R-tree with custom fields
+visualify portal rtree2d \
+  --x-field longitude \
+  --y-field latitude \
+  --id-field sample_id \
+  --output ./indexes/spatial \
+  ./data/samples.json
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning | Description |
+|------|---------|-------------|
+| `0` | Success | Command executed successfully |
+| `1` | General Error | Unspecified error occurred |
+| `2` | Invalid Arguments | Invalid or missing command arguments |
+| `3` | Configuration Error | Error in visualify.json configuration |
+| `4` | File Not Found | Required file not found |
+| `5` | Port In Use | Specified port is already in use |
+| `6` | Build Error | Error during build process |
+| `7` | Validation Error | Data validation failed |
+
+---
+
+## Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `VISUALIFY_PORT` | Default port for dev server | `3000` |
+| `VISUALIFY_HOST` | Default host for dev server | `localhost` |
+| `VISUALIFY_MODE` | Default mode (docs/portal) | `portal` |
+| `VISUALIFY_CONFIG` | Path to config file | `./config/visualify.json` |
+| `DEBUG` | Enable debug logging | `visualify:*` |
+
+---
+
+## Common Use Cases
+
+### Development Workflow
+
+```bash
+# 1. Initialize a new portal project
+visualify init portal ./my-portal
+
+# 2. Navigate to project
+cd ./my-portal
+
+# 3. Start development server
+visualify dev
+
+# 4. Load spatial data
+visualify portal load-json ./data/points.json
+
+# 5. Create R-tree index
+visualify portal rtree2d --output ./rtree ./data/points.json
+
+# 6. Build for production
+visualify portal build --output ./dist
+```
+
+### CI/CD Integration
+
+```bash
+#!/bin/bash
+set -e
+
+# Install visualifyjs
+npm i -g visualifyjs
+
+# Validate configuration
+visualify dev --dry-run
+
+# Build project
+visualify portal build --output ./dist
+
+# Verify build
+if [ ! -d "./dist" ]; then
+  echo "Build failed: dist directory not found"
+  exit 1
+fi
+```
+
+### Migration Script
+
+```bash
+#!/bin/bash
+
+# Update from v2.x to v3.0.0
+
+# 1. Uninstall old CLI
+npm uninstall -g @visualify/cli
+
+# 2. Install new CLI
+npm i -g visualifyjs
+
+# 3. Verify installation
+visualify --version
+
+# 4. Create visualify.json if it doesn't exist
+if [ ! -f "visualify.json" ]; then
+  echo '{"version": "3.0.0", "mode": "portal"}' > visualify.json
+  echo "Created visualify.json with default configuration"
+fi
+
+echo "Migration complete!"
+```
+
+---
+
+## Troubleshooting
+
+### Command not found
+
+```bash
+# Check if installed
+which visualify
+
+# If not found, reinstall
+npm i -g visualifyjs
+
+# Or use npx
+npx visualifyjs --version
+```
+
+### Port already in use
+
+```bash
+# Use a different port
+visualify dev --port 8080
+
+# Or let the CLI find an available port
+visualify dev --port 0
+```
+
+### Configuration errors
+
+```bash
+# Validate configuration
+visualify dev --dry-run
+
+# Check configuration file
+cat visualify.json
+```
+
+---
+
+## Related Documentation
+
+- [Migration Guide](../migration/v3-migration.md)
+- [Configuration Reference](../configuration/visualify-json.md)
+- [Quick Start](../../docs/quickstart.md)