visualifyjs 2.5.3 → 3.0.0

package/src/editor/utils/chartValidator.js

@@ -0,0 +1,263 @@
+/**
+ * @fileoverview Chart Configuration Validator
+ * @module editor/utils/chartValidator
+ *
+ * Validates chart configurations for different chart types.
+ */
+
+/**
+ * Validation error
+ */
+class ValidationError extends Error {
+	constructor(message, field = null) {
+		super(message);
+		this.name = 'ValidationError';
+		this.field = field;
+	}
+}
+
+/**
+ * Chart type definitions and their required fields
+ */
+const CHART_SCHEMAS = {
+	scatter: {
+		required: ['data'],
+		dataFormat: [
+			{ x: 'number', y: 'number' },
+			{ value: 'array' },
+		],
+	},
+	scatter3d: {
+		required: ['data'],
+		dataFormat: [{ x: 'number', y: 'number', z: 'number' }],
+	},
+	bar: {
+		required: ['data'],
+		dataFormat: [{ category: 'string', value: 'number' }],
+	},
+	bar3d: {
+		required: ['data'],
+		dataFormat: [{ category: 'string', value: 'number' }],
+	},
+	line: {
+		required: ['data'],
+		dataFormat: [{ x: 'any', y: 'number' }],
+	},
+	line3d: {
+		required: ['data'],
+		dataFormat: [{ x: 'number', y: 'number', z: 'number' }],
+	},
+	pie: {
+		required: ['data'],
+		dataFormat: [{ name: 'string', value: 'number' }],
+	},
+	radar: {
+		required: ['data', 'options.radar.indicator'],
+		dataFormat: [{ name: 'string', value: 'array' }],
+	},
+	funnel: {
+		required: ['data'],
+		dataFormat: [{ name: 'string', value: 'number' }],
+	},
+	heatmap: {
+		required: ['data'],
+		dataFormat: ['array'],
+	},
+	boxplot: {
+		required: ['data'],
+		dataFormat: ['array'],
+	},
+	surface3d: {
+		required: [],
+		dataFormat: [],
+	},
+};
+
+/**
+ * Validate data point against format
+ * @param {Object} dataPoint - Data point to validate
+ * @param {Object} format - Expected format
+ * @returns {boolean}
+ */
+function validateDataPoint(dataPoint, format) {
+	if (typeof format === 'string') {
+		if (format === 'array') {
+			return Array.isArray(dataPoint);
+		}
+		return typeof dataPoint === format;
+	}
+
+	if (typeof format === 'object' && format !== null) {
+		return Object.entries(format).every(([key, type]) => {
+			if (!(key in dataPoint)) return false;
+
+			const value = dataPoint[key];
+			if (type === 'any') return true;
+			if (type === 'array') return Array.isArray(value);
+			if (type === 'number')
+				return typeof value === 'number' || !isNaN(parseFloat(value));
+			return typeof value === type;
+		});
+	}
+
+	return true;
+}
+
+/**
+ * Get nested value from object
+ * @param {Object} obj - Object to traverse
+ * @param {string} path - Dot-separated path
+ * @returns {any}
+ */
+function getNestedValue(obj, path) {
+	return path.split('.').reduce((current, key) => {
+		return current?.[key];
+	}, obj);
+}
+
+/**
+ * Validate chart configuration
+ * @param {Object} chart - Chart configuration
+ * @returns {Object} Validation result
+ */
+export function validateChart(chart) {
+	const errors = [];
+	const warnings = [];
+
+	// Check required fields
+	if (!chart.type) {
+		errors.push(new ValidationError('Chart type is required', 'type'));
+	}
+
+	if (!chart.title) {
+		warnings.push(new ValidationError('Chart title is recommended', 'title'));
+	}
+
+	const schema = CHART_SCHEMAS[chart.type];
+	if (!schema) {
+		errors.push(new ValidationError(`Unknown chart type: ${chart.type}`, 'type'));
+		return { valid: false, errors, warnings };
+	}
+
+	// Check schema requirements
+	for (const field of schema.required) {
+		const value = getNestedValue(chart, field);
+		if (value === undefined || value === null) {
+			errors.push(new ValidationError(`Missing required field: ${field}`, field));
+		}
+	}
+
+	// Validate data format
+	if (chart.data && Array.isArray(chart.data)) {
+		if (chart.data.length === 0) {
+			warnings.push(new ValidationError('Chart has no data points', 'data'));
+		} else {
+			// Check first data point against expected formats
+			const firstPoint = chart.data[0];
+			const validFormat = schema.dataFormat.some((format) =>
+				validateDataPoint(firstPoint, format),
+			);
+
+			if (!validFormat && schema.dataFormat.length > 0) {
+				const expectedFormat = schema.dataFormat
+					.map((f) =>
+						typeof f === 'string'
+							? f
+							: JSON.stringify(f),
+					)
+					.join(' or ');
+				warnings.push(
+					new ValidationError(
+						`Data format may be incorrect. Expected: ${expectedFormat}`,
+						'data',
+					),
+				);
+			}
+		}
+	} else if (schema.required.includes('data')) {
+		errors.push(new ValidationError('Chart data must be an array', 'data'));
+	}
+
+	// Validate 3D specific requirements
+	if (chart.type.includes('3d')) {
+		// Note: In a real implementation, we would check for WebGL support here
+		warnings.push(
+			new ValidationError(
+				'3D charts require WebGL support in the browser',
+				'type',
+			),
+		);
+	}
+
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings,
+	};
+}
+
+/**
+ * Validate complete configuration
+ * @param {Object} config - Full configuration
+ * @returns {Object} Validation result
+ */
+export function validateConfig(config) {
+	const errors = [];
+	const warnings = [];
+
+	if (!config) {
+		errors.push(new ValidationError('Configuration is required'));
+		return { valid: false, errors, warnings };
+	}
+
+	if (!config.charts || !Array.isArray(config.charts)) {
+		errors.push(new ValidationError('Configuration must have a charts array'));
+	} else {
+		// Validate each chart
+		config.charts.forEach((chart, index) => {
+			const result = validateChart(chart);
+			result.errors.forEach((error) => {
+				error.field = `charts[${index}].${error.field}`;
+				errors.push(error);
+			});
+			result.warnings.forEach((warning) => {
+				warning.field = `charts[${index}].${warning.field}`;
+				warnings.push(warning);
+			});
+		});
+	}
+
+	// Validate layout
+	if (config.layout) {
+		const { rows, cols } = config.layout;
+		if (rows && (typeof rows !== 'number' || rows < 1)) {
+			errors.push(new ValidationError('Layout rows must be a positive number'));
+		}
+		if (cols && (typeof cols !== 'number' || cols < 1)) {
+			errors.push(new ValidationError('Layout cols must be a positive number'));
+		}
+	}
+
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings,
+	};
+}
+
+/**
+ * Format validation errors for display
+ * @param {Array} errors - Array of ValidationError
+ * @returns {string}
+ */
+export function formatValidationErrors(errors) {
+	return errors
+		.map((error) => {
+			const field = error.field ? `[${error.field}] ` : '';
+			return `${field}${error.message}`;
+		})
+		.join('\n');
+}
+
+export { ValidationError, CHART_SCHEMAS };
+export default validateChart;

package/src/entries/charts3d.js

@@ -0,0 +1,70 @@
+/**
+ * 3D Charts Entry Point
+ * @description Separate chunk for 3D visualization components
+ * Loaded on demand when 3D chart types are detected
+ * Global name: Visualify3D
+ *
+ * External dependencies (not bundled):
+ * - three
+ * - @react-three/fiber
+ * - @react-three/drei
+ * - echarts-gl
+ */
+
+// 3D visualization components
+export { default as Scatter3D } from '../core/components/Scatter3D';
+export { default as Bar3D } from '../core/components/Bar3D';
+export { default as Surface3D } from '../core/components/Surface3D';
+export { default as Line3D } from '../core/components/Line3D';
+export { default as ThreeScene } from '../core/components/ThreeScene';
+export { default as ThreeCustom } from '../core/components/ThreeCustom';
+
+// ECharts GL integration (lazy loading, WebGL detection)
+export {
+	isWebGLSupported,
+	getWebGLInfo,
+	loadEChartsGL,
+	preloadEChartsGL,
+	getLoadingState,
+	display3DError,
+	cleanupWebGL,
+	handleWebGLContextLoss,
+} from '../core/modules/echarts/gl';
+
+// Three.js module
+export { default as ThreeJS } from '../core/modules/threejs/index';
+
+/**
+ * Visualify3D namespace
+ * 3D chart components loaded on demand
+ */
+const Visualify3D = {
+	version: process.env.VISUALIFY_VERSION || 'dev',
+
+	/**
+	 * Check if the current environment supports 3D rendering
+	 * @returns {boolean}
+	 */
+	isSupported() {
+		try {
+			const canvas = document.createElement('canvas');
+			const gl =
+				canvas.getContext('webgl2') ||
+				canvas.getContext('webgl') ||
+				canvas.getContext('experimental-webgl');
+			return !!gl;
+		} catch (e) {
+			return false;
+		}
+	},
+
+	/**
+	 * Preload 3D dependencies in the background
+	 */
+	async preload() {
+		const { preloadEChartsGL } = await import('../core/modules/echarts/gl');
+		preloadEChartsGL();
+	},
+};
+
+export default Visualify3D;

package/src/entries/core.js

@@ -0,0 +1,78 @@
+/**
+ * Core 2D Charting Entry Point
+ * @description Lightweight bundle with core charting capabilities
+ * Includes ECharts, Recharts, parsers, themes, and essential widgets
+ * Global name: VisualifyCore
+ */
+
+import '../_css/index.css';
+import 'bootstrap/dist/css/bootstrap.min.css';
+
+import Recharts from '../core/recharts';
+import LiveEditor from '../core/liveEditor';
+import { VisualifyProvider, useAppContext } from '../core/appContext';
+
+// Core chart components
+export { default as ReCharts } from '../core/modules/echarts';
+export { default as EChartSwitcher } from '../core/modules/echartswitcher';
+
+// Chart utilities and parsers
+export * from '../core/parser/echart.data';
+export * from '../core/parser/echart.features';
+export * from '../core/parser/echart.series';
+export * from '../core/parser/echart.types';
+export * from '../core/parser/echart.parser';
+export * from '../core/parser/echart.hilbert';
+
+// ECharts utilities and presets
+export * from '../core/modules/echartsUtils';
+export { fetchPresetFromURL, getEmbeddedPreset } from '../core/modules/echarts/presetHandler';
+export * from '../core/modules/echarts/common';
+
+// Theme system
+export { default as ThemeSelector } from '../core/themes/themeSelector';
+export * from '../core/themes/modern';
+
+// Shared widgets
+export { default as ErrorBoundary } from '../core/widgets/errorBoundary';
+export { default as CircularProgress } from '../core/widgets/circularProgress';
+
+// Re-export core classes
+export { Recharts, LiveEditor, VisualifyProvider, useAppContext };
+
+/**
+ * VisualifyCore namespace
+ * Contains core 2D charting exports
+ */
+const VisualifyCore = {
+	// Version info (replaced during build)
+	version: process.env.VISUALIFY_VERSION || 'dev',
+
+	// Core classes
+	Recharts,
+	LiveEditor,
+
+	// React context
+	VisualifyProvider,
+	useAppContext,
+
+	/**
+	 * Create a chart instance
+	 * @param {Object} config - Chart configuration
+	 * @returns {Recharts} Recharts instance
+	 */
+	createChart(config) {
+		return new Recharts(config);
+	},
+
+	/**
+	 * Create a live editor instance
+	 * @param {Object} config - Editor configuration
+	 * @returns {LiveEditor} LiveEditor instance
+	 */
+	createEditor(config) {
+		return new LiveEditor(config);
+	},
+};
+
+export default VisualifyCore;

package/src/entries/docs.js

@@ -0,0 +1,154 @@
+/**
+ * Docsify Plugin Entry Point
+ * @description Lightweight bundle for Docsify integration
+ * Exports only the charting capabilities needed for documentation
+ * Global name: VisualifyDocs
+ */
+
+import DocsifyPlugin from '../docsify/plugin';
+import { processMarkdown, processVisualifyBlocks, extractConfigs } from '../docsify/markdown';
+import Recharts from '../core/recharts';
+import LiveEditor from '../core/liveEditor';
+import { VisualifyProvider } from '../core/appContext';
+
+// Re-export shared components for docs usage
+export { Recharts, LiveEditor, VisualifyProvider };
+
+/**
+ * Docsify plugin initialization
+ * Registers Visualify components as Docsify plugins
+ */
+function install(hook, vm) {
+	hook.init(function () {
+		// Initialize any required setup before Docsify starts
+		console.log('[VisualifyDocs] Initializing Docsify plugin...');
+	});
+
+	hook.mounted(function () {
+		// Auto-mount charts with data-visualify attribute after each page mount
+		const chartElements = document.querySelectorAll('[data-visualify]');
+		chartElements.forEach((el) => {
+			try {
+				const config = JSON.parse(el.dataset.visualify || '{}');
+				const chart = new Recharts(config);
+				chart.mount(el);
+			} catch (e) {
+				console.error('[VisualifyDocs] Failed to mount chart:', e);
+			}
+		});
+	});
+
+	hook.doneEach(function () {
+		// Re-mount charts after each navigation (SPA behavior)
+		const chartElements = document.querySelectorAll('[data-visualify]');
+		chartElements.forEach((el) => {
+			// Skip if already mounted
+			if (el.dataset.visualifyMounted) return;
+
+			try {
+				const config = JSON.parse(el.dataset.visualify || '{}');
+				const chart = new Recharts(config);
+				chart.mount(el);
+				el.dataset.visualifyMounted = 'true';
+			} catch (e) {
+				console.error('[VisualifyDocs] Failed to mount chart:', e);
+			}
+		});
+	});
+}
+
+/**
+ * Global install function for UMD builds
+ * Attaches to window.VisualifyDocs
+ */
+const VisualifyDocs = {
+	// Core charting classes
+	Recharts,
+	LiveEditor,
+
+	// Provider for React context
+	VisualifyProvider,
+
+	// Docsify plugin
+	plugin: DocsifyPlugin,
+
+	// Markdown processing utilities
+	markdown: {
+		process: processMarkdown,
+		processBlocks: processVisualifyBlocks,
+		extractConfigs,
+	},
+
+	// Legacy install function for backwards compatibility
+	install,
+
+	// Version info (replaced during build)
+	version: process.env.VISUALIFY_VERSION || 'dev',
+
+	/**
+	 * Create a chart instance
+	 * @param {Object} config - Chart configuration
+	 * @returns {Recharts} Recharts instance
+	 */
+	createChart(config) {
+		return new Recharts(config);
+	},
+
+	/**
+	 * Create a live editor instance
+	 * @param {Object} config - Editor configuration
+	 * @returns {LiveEditor} LiveEditor instance
+	 */
+	createEditor(config) {
+		return new LiveEditor(config);
+	},
+
+	/**
+	 * Mount all charts with data-visualify attribute in container
+	 * @param {string|Element} container - Container element or selector
+	 */
+	mountAll(container = document) {
+		const root = typeof container === 'string'
+			? document.querySelector(container)
+			: container;
+
+		if (!root) {
+			console.error('[VisualifyDocs] Container not found:', container);
+			return;
+		}
+
+		const chartElements = root.querySelectorAll('[data-visualify]');
+		chartElements.forEach((el) => {
+			// Skip if already mounted
+			if (el.dataset.visualifyMounted) return;
+
+			try {
+				const config = JSON.parse(el.dataset.visualify || '{}');
+				const chart = new Recharts(config);
+				chart.mount(el);
+				el.dataset.visualifyMounted = 'true';
+			} catch (e) {
+				console.error('[VisualifyDocs] Failed to mount chart:', e);
+			}
+		});
+	},
+
+	/**
+	 * Process visualify code blocks in markdown content
+	 * @param {string} content - Markdown content
+	 * @returns {string} HTML with visualify charts
+	 */
+	processMarkdown(content) {
+		return processVisualifyBlocks(content);
+	},
+};
+
+// Auto-install if Docsify is present
+if (typeof window !== 'undefined' && window.$docsify) {
+	window.$docsify.plugins = [].concat(
+		window.$docsify.plugins || [],
+		DocsifyPlugin.install
+	);
+}
+
+export default VisualifyDocs;

package/src/entries/pages.js

@@ -0,0 +1,93 @@
+/**
+ * Page Mode Entry Point
+ * @description Full page mode bundle with all portal/application components
+ * Loaded on demand when mode is 'pages' or standalone portal usage
+ * Global name: VisualifyPages
+ */
+
+import CreateApp from '../core/visualify';
+
+// Page components
+export { default as JsonPage } from '../core/pages/jsonPage';
+export { default as LoadingPage } from '../core/pages/loading';
+export { default as ErrorPage } from '../core/pages/error';
+export { default as NotFoundPage } from '../core/pages/404';
+
+// Layout widgets
+export { default as Layout } from '../core/widgets/layout';
+export { default as Header } from '../core/widgets/header';
+export { default as Footer } from '../core/widgets/footer';
+export { default as Controller } from '../core/widgets/controller';
+export { default as GridLayout } from '../core/widgets/layout/Grid';
+export { default as Mapping } from '../core/widgets/mapping';
+
+// Visualization components (page mode specific)
+export { default as Scatter } from '../core/components/Scatter';
+export { default as ScatterBio } from '../core/components/ScatterBio';
+export { default as ScatterL } from '../core/components/scatterL';
+export { default as VisiumPlot } from '../core/components/VisiumPlot';
+export { default as Visium } from '../core/components/visium';
+export { default as DotPlot } from '../core/components/dotplot';
+export { default as Macaron } from '../core/components/macaron';
+export { default as Ratio } from '../core/components/ratio';
+export { default as Timeline } from '../core/components/timeline';
+export { default as Selection } from '../core/components/selection';
+export { default as SearchBar } from '../core/components/searchbar';
+export { default as Browser } from '../core/components/browser';
+export { default as List } from '../core/components/list';
+export { default as Html } from '../core/components/html';
+export { default as Markdown } from '../core/components/markdown';
+
+// Router components
+export { default as JsonRouter } from '../core/router/jsonRouter';
+export * from '../core/router/alias';
+
+// Data fetching utilities
+export { default as fetchData } from '../core/fetch/fetch';
+export { default as condFetch } from '../core/fetch/condfetch';
+export { default as vfetch } from '../core/fetch/vfetch';
+export { default as jsonFetch } from '../core/fetch/json';
+
+// Plotly support
+export { default as Replotly } from '../core/modules/replotly';
+export * from '../core/parser/plotly.data';
+export * from '../core/parser/plotly.layout';
+export * from '../core/parser/plotly.config';
+export * from '../core/parser/plotly.violin';
+
+// Data parser (for page mode API fetching)
+export { default as fetchDataParser } from '../core/parser/echart.parser';
+export * from '../core/parser/echart.parser';
+export * from '../core/parser/echart.hilbert';
+
+// Web vitals
+export { default as reportWebVitals } from '../_utils/reportWebVitals';
+
+// Re-export CreateApp
+export { CreateApp };
+
+/**
+ * VisualifyPages namespace
+ * Full page mode application bundle
+ */
+const VisualifyPages = {
+	version: process.env.VISUALIFY_VERSION || 'dev',
+
+	// Core application creator
+	createApp: CreateApp,
+
+	/**
+	 * Initialize page mode application
+	 * @param {Object} config - Application configuration
+	 */
+	init(config) {
+		if (!config) {
+			throw new Error('[VisualifyPages] Configuration object is required');
+		}
+		config.mode = config.mode || 'pages';
+		CreateApp(config);
+		console.log(`[VisualifyPages] v${this.version} initialized`);
+	},
+};
+
+export default VisualifyPages;