visualifyjs 2.5.3-2.dev → 3.0.0

package/src/docsify/markdown.js

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview Docsify Markdown Processor for Visualify
+ * @module docsify/markdown
+ *
+ * Parses visualify code blocks in markdown and converts them
+ * to HTML with data attributes for chart mounting.
+ */
+
+/**
+ * Default chart configuration
+ * @type {Object}
+ */
+const DEFAULT_CONFIG = {
+	type: 'scatter',
+};
+
+/**
+ * Valid chart types
+ * @type {string[]}
+ */
+const VALID_CHART_TYPES = [
+	'scatter',
+	'scatter3d',
+	'line',
+	'bar',
+	'pie',
+	'heatmap',
+	'violin',
+	'dotplot',
+	'hilbert',
+	'visium',
+];
+
+/**
+ * Validate and normalize chart configuration
+ * @param {Object} config - Raw configuration object
+ * @returns {Object} Normalized configuration
+ */
+function validateConfig(config) {
+	if (!config || typeof config !== 'object') {
+		console.warn('[VisualifyDocs] Invalid config, using defaults');
+		return { ...DEFAULT_CONFIG };
+	}
+
+	const normalized = { ...DEFAULT_CONFIG, ...config };
+
+	// Validate chart type
+	if (normalized.type && !VALID_CHART_TYPES.includes(normalized.type)) {
+		console.warn(
+			`[VisualifyDocs] Unknown chart type "${normalized.type}", defaulting to "scatter"`
+		);
+		normalized.type = 'scatter';
+	}
+
+	// Ensure data property exists
+	if (!normalized.data && !normalized.src) {
+		console.warn('[VisualifyDocs] No data or src provided, chart may fail to render');
+	}
+
+	return normalized;
+}
+
+/**
+ * Parse JSON safely with error handling
+ * @param {string} json - JSON string to parse
+ * @param {string} [context] - Context for error messages
+ * @returns {Object|null} Parsed object or null on error
+ */
+function safeJsonParse(json, context = 'unknown') {
+	try {
+		return JSON.parse(json);
+	} catch (err) {
+		console.warn(`[VisualifyDocs] JSON parse error in ${context}:`, err.message);
+		return null;
+	}
+}
+
+/**
+ * Generate a unique ID for chart containers
+ * @returns {string} Unique ID
+ */
+function generateChartId() {
+	return `visualify-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Process inline visualify configuration
+ * @param {string} code - Code block content (JSON)
+ * @returns {string} HTML output
+ */
+function processInlineConfig(code) {
+	const config = safeJsonParse(code, 'inline config');
+
+	if (!config) {
+		return renderError('Invalid JSON in visualify code block');
+	}
+
+	const normalizedConfig = validateConfig(config);
+	const chartId = generateChartId();
+
+	return renderChartContainer(chartId, normalizedConfig);
+}
+
+/**
+ * Process external file reference
+ * @param {Object} config - Configuration with src property
+ * @returns {string} HTML output
+ */
+function processExternalFile(config) {
+	const chartId = generateChartId();
+	return renderChartContainer(chartId, config);
+}
+
+/**
+ * Render chart container HTML
+ * @param {string} id - Unique chart ID
+ * @param {Object} config - Chart configuration
+ * @returns {string} HTML string
+ */
+function renderChartContainer(id, config) {
+	const configJson = JSON.stringify(config).replace(/"/g, '"');
+	const { type = 'scatter' } = config;
+
+	return (
+		`<div class="visualify-chart-wrapper" data-visualify-type="${type}">` +
+		`<div ` +
+		`id="${id}" ` +
+		`class="visualify-chart-container" ` +
+		`data-visualify="${configJson}" ` +
+		`style="width: 100%; min-height: 400px;"` +
+		`></div>` +
+		`</div>`
+	);
+}
+
+/**
+ * Render error message HTML
+ * @param {string} message - Error message
+ * @returns {string} HTML string
+ */
+function renderError(message) {
+	return (
+		`<div class="visualify-error" style="` +
+		`padding: 16px; ` +
+		`border: 1px solid #ff4d4f; ` +
+		`border-radius: 4px; ` +
+		`background: #fff2f0; ` +
+		`color: #cf1322; ` +
+		`margin: 16px 0;` +
+		`">` +
+		`<strong>Visualify Error:</strong> ${escapeHtml(message)}` +
+		`</div>`
+	);
+}
+
+/**
+ * Escape HTML special characters
+ * @param {string} text - Text to escape
+ * @returns {string} Escaped text
+ */
+function escapeHtml(text) {
+	const div = typeof document !== 'undefined' ? document.createElement('div') : null;
+	if (div) {
+		div.textContent = text;
+		return div.innerHTML;
+	}
+	// Server-side fallback
+	return text
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#039;');
+}
+
+/**
+ * Process visualify code block content
+ * @param {string} code - Code block content
+ * @returns {string} HTML output
+ */
+function processMarkdown(code) {
+	if (!code || typeof code !== 'string') {
+		return renderError('Empty visualify code block');
+	}
+
+	const trimmedCode = code.trim();
+
+	if (!trimmedCode) {
+		return renderError('Empty visualify code block');
+	}
+
+	// Try to parse as JSON
+	const config = safeJsonParse(trimmedCode, 'markdown processor');
+
+	if (!config) {
+		return renderError('Invalid JSON in visualify code block. Ensure your configuration is valid JSON.');
+	}
+
+	// Check for external file reference
+	if (config.src) {
+		return processExternalFile(config);
+	}
+
+	// Process inline configuration
+	return processInlineConfig(trimmedCode);
+}
+
+/**
+ * Process visualify code blocks in full markdown content
+ * Useful for pre-processing before Docsify renders
+ * @param {string} content - Full markdown content
+ * @returns {string} Processed markdown with HTML placeholders
+ */
+function processVisualifyBlocks(content) {
+	if (!content || typeof content !== 'string') {
+		return content;
+	}
+
+	// Match visualify code blocks
+	const visualifyRegex = /```visualify\n([\s\S]*?)```/g;
+
+	return content.replace(visualifyRegex, (match, code) => {
+		return processMarkdown(code);
+	});
+}
+
+/**
+ * Extract visualify configurations from markdown
+ * Useful for search indexing or pre-loading
+ * @param {string} content - Markdown content
+ * @returns {Array<Object>} Array of chart configurations
+ */
+function extractConfigs(content) {
+	if (!content || typeof content !== 'string') {
+		return [];
+	}
+
+	const configs = [];
+	const visualifyRegex = /```visualify\n([\s\S]*?)```/g;
+	let match;
+
+	while ((match = visualifyRegex.exec(content)) !== null) {
+		const config = safeJsonParse(match[1], 'config extraction');
+		if (config) {
+			configs.push(validateConfig(config));
+		}
+	}
+
+	return configs;
+}
+
+/**
+ * Check if content has visualify blocks (fast check)
+ * @param {string} content - Markdown content
+ * @returns {boolean}
+ */
+function hasVisualifyBlocks(content) {
+	return typeof content === 'string' && content.includes('```visualify');
+}
+
+export {
+	processMarkdown,
+	processVisualifyBlocks,
+	extractConfigs,
+	validateConfig,
+	hasVisualifyBlocks,
+	DEFAULT_CONFIG,
+	VALID_CHART_TYPES,
+};
+
+export default processMarkdown;

package/src/docsify/plugin.js

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview Docsify Plugin Hook for Visualify
+ * @module docsify/plugin
+ *
+ * Hooks into Docsify's lifecycle to process visualify code blocks
+ * and auto-mount charts with data-visualify attribute.
+ */
+
+import { processMarkdown } from './markdown';
+
+/**
+ * Chart instance registry for cleanup
+ * @type {WeakMap<Element, Object>}
+ */
+const chartRegistry = new WeakMap();
+
+/**
+ * Lazy-loaded Visualify components
+ * @type {Object|null}
+ */
+let VisualifyComponents = null;
+
+/**
+ * Loading promise to prevent duplicate loads
+ * @type {Promise|null}
+ */
+let loadPromise = null;
+
+/**
+ * Lazy load Visualify components only when needed
+ * @returns {Promise<Object>} Visualify components
+ */
+async function loadVisualifyComponents() {
+	if (VisualifyComponents) {
+		return VisualifyComponents;
+	}
+
+	if (loadPromise) {
+		return loadPromise;
+	}
+
+	loadPromise = import('../core/recharts')
+		.then((module) => {
+			VisualifyComponents = {
+				Recharts: module.default,
+			};
+			return VisualifyComponents;
+		})
+		.catch((err) => {
+			console.error('[VisualifyDocs] Failed to load Visualify components:', err);
+			throw err;
+		});
+
+	return loadPromise;
+}
+
+/**
+ * Mount a chart on a single element
+ * @param {Element} el - DOM element to mount chart on
+ * @param {Object} [config] - Optional config (parsed from data-visualify if not provided)
+ */
+async function mountChart(el, config) {
+	// Skip if already mounted
+	if (el.dataset.visualifyMounted === 'true') {
+		return;
+	}
+
+	try {
+		const chartConfig = config || JSON.parse(el.dataset.visualify || '{}');
+
+		// Handle external file reference
+		if (chartConfig.src) {
+			const response = await fetch(chartConfig.src);
+			if (!response.ok) {
+				throw new Error(`Failed to fetch ${chartConfig.src}: ${response.statusText}`);
+			}
+			const externalConfig = await response.json();
+			Object.assign(chartConfig, externalConfig);
+			delete chartConfig.src;
+		}
+
+		// Load Visualify components lazily
+		const { Recharts } = await loadVisualifyComponents();
+
+		// Create and mount chart
+		const chart = new Recharts(chartConfig);
+		chart.mount(el);
+
+		// Track for cleanup
+		chartRegistry.set(el, chart);
+		el.dataset.visualifyMounted = 'true';
+
+		// Store config for potential re-mounting
+		el.dataset.visualify = JSON.stringify(chartConfig);
+	} catch (err) {
+		console.error('[VisualifyDocs] Failed to mount chart:', err);
+
+		// Display error in place of chart
+		el.innerHTML = `<div style="
+			padding: 16px;
+			border: 1px solid #ff4d4f;
+			border-radius: 4px;
+			background: #fff2f0;
+			color: #cf1322;
+		">
+			<strong>Visualify Error:</strong> ${err.message}
+		</div>`;
+	}
+}
+
+/**
+ * Mount all charts in a container
+ * @param {Element} [container] - Container element (defaults to document)
+ */
+async function mountAllCharts(container = document) {
+	const elements = container.querySelectorAll('[data-visualify]:not([data-visualify-mounted="true"])');
+
+	if (elements.length === 0) {
+		return;
+	}
+
+	// Load components once for all charts
+	await loadVisualifyComponents();
+
+	// Mount all charts
+	const mountPromises = Array.from(elements).map((el) => mountChart(el));
+	await Promise.all(mountPromises);
+}
+
+/**
+ * Cleanup charts in a container (for SPA navigation)
+ * @param {Element} [container] - Container element (defaults to document)
+ */
+function cleanupCharts(container = document) {
+	const elements = container.querySelectorAll('[data-visualify]');
+
+	elements.forEach((el) => {
+		const chart = chartRegistry.get(el);
+		if (chart && typeof chart.dispose === 'function') {
+			chart.dispose();
+		}
+		chartRegistry.delete(el);
+		el.dataset.visualifyMounted = 'false';
+	});
+}
+
+/**
+ * Check if markdown contains visualify code blocks
+ * @param {string} content - Markdown content
+ * @returns {boolean}
+ */
+function hasVisualifyBlocks(content) {
+	return /```visualify\n/.test(content);
+}
+
+/**
+ * Docsify plugin install function
+ * @param {Object} hook - Docsify hook object
+ * @param {Object} vm - Docsify vm instance
+ */
+function install(hook, vm) {
+	// Initialize - called before Docsify starts
+	hook.init(function () {
+		console.log('[VisualifyDocs] Initializing Docsify plugin...');
+
+		// Add custom markdown configuration
+		if (window.$docsify && window.$docsify.markdown) {
+			const originalRenderer = window.$docsify.markdown.renderer;
+
+			window.$docsify.markdown.renderer = {
+				...originalRenderer,
+				code: function (code, lang) {
+					if (lang === 'visualify') {
+						return processMarkdown(code);
+					}
+					// Fall back to original renderer for other languages
+					if (originalRenderer && originalRenderer.code) {
+						return originalRenderer.code.call(this, code, lang);
+					}
+					return `<pre><code class="lang-${lang}">${code}</code></pre>`;
+				},
+			};
+		}
+	});
+
+	// Before each page load - cleanup previous charts
+	hook.beforeEach(function (content) {
+		// Check if we need to load Visualify (optimization)
+		if (hasVisualifyBlocks(content)) {
+			// Preload components in background
+			loadVisualifyComponents().catch(() => {
+				// Silently fail - will retry on mount
+			});
+		}
+		return content;
+	});
+
+	// After each markdown parsing - process any remaining blocks
+	hook.afterEach(function (html, next) {
+		// If markdown renderer didn't catch all blocks (e.g., via plugin order)
+		// We can process them here as a fallback
+		next(html);
+	});
+
+	// Mounted - initial page load
+	hook.mounted(function () {
+		console.log('[VisualifyDocs] Docsify mounted, scanning for charts...');
+		mountAllCharts();
+	});
+
+	// Done each - after each route change (SPA navigation)
+	hook.doneEach(function () {
+		console.log('[VisualifyDocs] Route changed, mounting charts...');
+		mountAllCharts();
+	});
+
+	// Destroyed - cleanup when leaving
+	hook.destroyed(function () {
+		console.log('[VisualifyDocs] Cleaning up charts...');
+		cleanupCharts();
+	});
+}
+
+/**
+ * Global API for manual chart mounting
+ */
+const VisualifyDocsify = {
+	install,
+	mountChart,
+	mountAllCharts,
+	cleanupCharts,
+	loadVisualifyComponents,
+
+	/**
+	 * Check if an element has a mounted chart
+	 * @param {Element} el - DOM element
+	 * @returns {boolean}
+	 */
+	isMounted(el) {
+		return el.dataset.visualifyMounted === 'true';
+	},
+
+	/**
+	 * Get chart instance for an element
+	 * @param {Element} el - DOM element
+	 * @returns {Object|null}
+	 */
+	getChart(el) {
+		return chartRegistry.get(el) || null;
+	},
+
+	/**
+	 * Version info
+	 */
+	version: process.env.VISUALIFY_VERSION || 'dev',
+};
+
+// Auto-install if Docsify is present
+if (typeof window !== 'undefined' && window.$docsify) {
+	window.$docsify.plugins = [].concat(
+		window.$docsify.plugins || [],
+		install
+	);
+	console.log('[VisualifyDocs] Auto-registered with Docsify');
+}
+
+export default VisualifyDocsify;
+export { install, mountChart, mountAllCharts, cleanupCharts, loadVisualifyComponents };

package/src/editor/README.md

@@ -0,0 +1,172 @@
+# Visualify Visual Editor
+
+A visual configuration editor for Visualify.js that makes it easy to create and edit chart configurations without writing JSON.
+
+## Features
+
+- **Drag-and-Drop Interface**: Build charts by dragging chart types from the sidebar
+- **Property Panels**: Dynamic forms for each chart type (2D and 3D)
+- **Live Preview**: Real-time chart rendering as you edit
+- **Import/Export**: Load and save `visualify.json` configurations
+- **Undo/Redo History**: Full editing history with keyboard shortcuts
+- **Auto-Save**: Automatic saving to localStorage
+- **Responsive Design**: Works on different screen sizes
+
+## Supported Chart Types
+
+### 2D Charts
+- Scatter
+- Bar
+- Line
+- Pie
+- Radar
+- Funnel
+- Heatmap
+- Box Plot
+
+### 3D Charts
+- 3D Scatter
+- 3D Bar
+- 3D Surface
+- 3D Line
+
+## Usage
+
+### CLI Command
+
+```bash
+# Open editor with default config
+visualify edit
+
+# Open specific config file
+visualify edit my-config.json
+
+# Custom port
+visualify edit --port 4000
+
+# Don't open browser automatically
+visualify edit --no-open
+```
+
+### Programmatic Usage
+
+```javascript
+import { mountEditor } from './editor';
+
+// Mount editor to a DOM element
+mountEditor('#editor-container', {
+  config: {
+    version: '3.0.0',
+    charts: [],
+    layout: { type: 'grid', rows: 1, cols: 1 },
+    theme: 'modern'
+  }
+});
+```
+
+## UI Layout
+
+```
++------------------------------------------+
+|  Toolbar (New, Open, Save, Export, Undo) |
++----------+----------------+--------------+
+|          |                |              |
+| Chart    |    Canvas      |  Properties  |
+| Types    |    (D&D)       |  Panel       |
+|          |                |              |
++----------+----------------+--------------+
+|  Status Bar (Errors, Auto-save status)   |
++------------------------------------------+
+```
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl/Cmd + Z` | Undo |
+| `Ctrl/Cmd + Y` | Redo |
+| `Ctrl/Cmd + Shift + Z` | Redo (alternative) |
+| `Ctrl/Cmd + S` | Export configuration |
+| `Escape` | Close modals |
+
+## File Structure
+
+```
+editor/
+├── index.js                 # Main entry point
+├── context/
+│   └── EditorContext.js     # React context for state management
+├── components/
+│   ├── Editor.jsx           # Main editor UI
+│   ├── ChartBuilder.jsx     # Drag-and-drop canvas
+│   ├── ChartTypeSidebar.jsx # Chart type selector
+│   ├── PropertyPanel.jsx    # Property editor
+│   ├── Preview.jsx          # Live preview
+│   └── StatusBar.jsx        # Status bar
+├── utils/
+│   └── chartValidator.js    # Configuration validation
+├── styles/
+│   └── editor.css           # Editor styles
+└── README.md                # This file
+```
+
+## Architecture
+
+### State Management
+
+The editor uses React Context for state management with the following structure:
+
+```javascript
+{
+  config: {
+    version: '3.0.0',
+    charts: [...],
+    layout: {...},
+    theme: 'modern'
+  },
+  selectedChartId: string | null,
+  history: {
+    past: [...],
+    present: {...},
+    future: [...]
+  }
+}
+```
+
+### Actions
+
+- `setConfig(config)` - Replace entire configuration
+- `addChart(chart)` - Add a new chart
+- `updateChart(id, updates)` - Update chart properties
+- `removeChart(id)` - Remove a chart
+- `setSelectedChart(id)` - Select a chart for editing
+- `undo()` / `redo()` - History navigation
+
+## Validation
+
+Charts are validated in real-time with checks for:
+
+- Required fields (type, data)
+- Data format compatibility
+- 3D WebGL support
+- Configuration completeness
+
+## Building
+
+The editor is built as a React application and bundled for distribution:
+
+```bash
+# Development
+npm run editor:dev
+
+# Build
+npm run editor:build
+```
+
+## Browser Support
+
+- Chrome/Edge 80+
+- Firefox 75+
+- Safari 13+
+
+3D charts require WebGL support.