visualifyjs 2.5.3-2.dev → 3.0.0

package/docs/docs/hmr.md

@@ -0,0 +1,165 @@
+# Hot Module Replacement (HMR)
+
+Visualify.js includes a built-in HMR system for development that enables instant chart updates without page reloads.
+
+## Overview
+
+HMR allows you to:
+- See chart changes instantly when editing configuration files
+- Preserve chart state during updates
+- Get visual feedback for configuration errors
+- Work efficiently with iterative chart design
+
+## How It Works
+
+The HMR system consists of:
+
+1. **File Watcher** - Monitors your visualization JSON files for changes
+2. **WebSocket Server** - Pushes updates to the browser
+3. **Client Handler** - Receives and applies updates while preserving state
+4. **Error Overlay** - Displays configuration errors without breaking the app
+
+## Enabling HMR
+
+### In Development Mode
+
+HMR is automatically enabled when using the Visualify CLI development server:
+
+```bash
+visualify dev
+```
+
+Or with a specific configuration:
+
+```bash
+visualify dev --config ./my-visualization.json
+```
+
+### Programmatic API
+
+Enable HMR when initializing Visualify:
+
+```javascript
+import { initHMR } from 'visualify';
+
+// Initialize HMR with custom options
+const hmr = initHMR({
+    wsUrl: 'ws://localhost:3000/__hmr',
+    reconnectDelay: 1000,
+    maxReconnectAttempts: 10,
+    debug: false
+});
+```
+
+### React Hook
+
+Use the `useHMR` hook in custom components:
+
+```javascript
+import { useHMR } from 'visualify';
+
+function MyChartComponent() {
+    useHMR({
+        onUpdate: (newConfig) => {
+            console.log('Configuration updated:', newConfig);
+        },
+        onError: (error) => {
+            console.error('HMR Error:', error);
+        }
+    });
+
+    return <div>{/* Chart content */}</div>;
+}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `wsUrl` | String | `'ws://localhost:3000/__hmr'` | WebSocket server URL |
+| `reconnectDelay` | Number | `1000` | Delay between reconnection attempts (ms) |
+| `maxReconnectAttempts` | Number | `10` | Maximum reconnection attempts |
+| `heartbeatInterval` | Number | `30000` | WebSocket heartbeat interval (ms) |
+| `debug` | Boolean | `false` | Enable debug logging |
+
+## State Preservation
+
+HMR preserves the following chart state during updates:
+
+- Current zoom level and pan position
+- Selected/highlighted data points
+- Tooltip visibility
+- Legend toggle states
+- User interactions
+
+To customize state preservation:
+
+```javascript
+import { preserveState } from 'visualify';
+
+preserveState('myChart', {
+    save: () => ({
+        zoom: chart.getZoom(),
+        selection: chart.getSelection()
+    }),
+    restore: (state) => {
+        chart.setZoom(state.zoom);
+        chart.setSelection(state.selection);
+    }
+});
+```
+
+## Error Handling
+
+HMR includes a visual error overlay that displays configuration errors:
+
+```javascript
+import { setErrorOverlay } from 'visualify';
+
+// Customize error overlay appearance
+setErrorOverlay({
+    position: 'top-right',
+    timeout: 5000,
+    theme: 'dark'
+});
+```
+
+## Disabling HMR
+
+To disable HMR (e.g., for production builds):
+
+```javascript
+// Set global flag before loading Visualify
+window.__VISUALIFY_HMR__ = { enabled: false };
+```
+
+Or via CLI:
+
+```bash
+visualify build --no-hmr
+```
+
+## Best Practices
+
+1. **Use HMR in development only** - Disable for production builds
+2. **Handle state compatibility** - Ensure restored state is compatible with new config
+3. **Test error scenarios** - Verify error overlays work with invalid configurations
+4. **Monitor WebSocket connection** - Check console for reconnection warnings
+
+## Troubleshooting
+
+### HMR Not Connecting
+
+- Verify the WebSocket URL matches your dev server
+- Check firewall settings for WebSocket connections
+- Ensure `window.__VISUALIFY_HMR__.enabled` is not set to `false`
+
+### State Not Preserved
+
+- Implement custom `preserveState` handlers for complex charts
+- Check that state keys match between save and restore
+
+### Performance Issues
+
+- Increase `reconnectDelay` if experiencing frequent reconnections
+- Disable HMR for charts with heavy data processing

package/docs/docs/i18n.md

@@ -0,0 +1,332 @@
+# Internationalization (i18n)
+
+Visualify.js provides built-in internationalization support for multi-language chart applications.
+
+## Overview
+
+The i18n system supports:
+- Multiple language packs
+- Runtime language switching
+- Custom translation keys
+- Number and date formatting
+- RTL (Right-to-Left) language support
+
+## Supported Languages
+
+Built-in language packs:
+
+| Language | Code | Status |
+|----------|------|--------|
+| English | `en` | ✓ Complete |
+| Chinese (Simplified) | `zh-CN` | ✓ Complete |
+| Chinese (Traditional) | `zh-TW` | ✓ Complete |
+| Japanese | `ja` | ✓ Complete |
+| Korean | `ko` | ✓ Complete |
+| Spanish | `es` | ✓ Complete |
+| French | `fr` | ✓ Complete |
+| German | `de` | ✓ Complete |
+| Russian | `ru` | ✓ Complete |
+| Arabic | `ar` | ✓ RTL Support |
+
+## Basic Usage
+
+### Setting the Language
+
+```javascript
+import { setLanguage, getLanguage } from 'visualify';
+
+// Set language
+setLanguage('zh-CN');
+
+// Get current language
+const currentLang = getLanguage(); // 'zh-CN'
+```
+
+### In Configuration
+
+```json
+{
+    "type": "line",
+    "title": "Sales Data",
+    "i18n": {
+        "locale": "zh-CN",
+        "fallback": "en"
+    },
+    "data": { ... }
+}
+```
+
+## Translation Keys
+
+### Default Keys
+
+Visualify automatically translates these keys:
+
+| Key | English | 中文 |
+|-----|---------|------|
+| `chart.title` | Chart Title | 图表标题 |
+| `chart.noData` | No data available | 暂无数据 |
+| `chart.loading` | Loading... | 加载中... |
+| `tooltip.clickForDetails` | Click for details | 点击查看详情 |
+| `legend.show` | Show | 显示 |
+| `legend.hide` | Hide | 隐藏 |
+| `axis.x` | X Axis | X轴 |
+| `axis.y` | Y Axis | Y轴 |
+| `data.value` | Value | 数值 |
+| `data.category` | Category | 类别 |
+
+### Custom Translations
+
+```javascript
+import { addTranslations } from 'visualify';
+
+// Add custom translations
+addTranslations('en', {
+    'custom.revenue': 'Revenue',
+    'custom.profit': 'Profit Margin',
+    'custom.customers': 'Active Customers'
+});
+
+addTranslations('zh-CN', {
+    'custom.revenue': '收入',
+    'custom.profit': '利润率',
+    'custom.customers': '活跃客户'
+});
+```
+
+### Using Translations
+
+```json
+{
+    "type": "bar",
+    "title": {
+        "text": "@custom.revenue"
+    },
+    "series": [{
+        "name": "@custom.profit",
+        "data": [25, 30, 35]
+    }]
+}
+```
+
+## Number Formatting
+
+### Locale-Aware Formatting
+
+```javascript
+import { formatNumber, formatCurrency } from 'visualify';
+
+// Format number based on locale
+formatNumber(1234567.89, 'de');    // "1.234.567,89"
+formatNumber(1234567.89, 'en');    // "1,234,567.89"
+
+// Currency formatting
+formatCurrency(1234.50, 'USD', 'en');  // "$1,234.50"
+formatCurrency(1234.50, 'EUR', 'de');  // "1.234,50 €"
+```
+
+### In Configuration
+
+```json
+{
+    "type": "line",
+    "yAxis": {
+        "type": "value",
+        "formatter": {
+            "type": "currency",
+            "currency": "USD",
+            "locale": "en"
+        }
+    }
+}
+```
+
+## Date Formatting
+
+### Locale-Aware Dates
+
+```javascript
+import { formatDate, parseDate } from 'visualify';
+
+// Format dates
+formatDate(new Date(), 'zh-CN', { dateStyle: 'long' });
+// "2024年1月15日"
+
+formatDate(new Date(), 'en', { dateStyle: 'medium' });
+// "Jan 15, 2024"
+```
+
+### Time Series Charts
+
+```json
+{
+    "type": "line",
+    "xAxis": {
+        "type": "time",
+        "timeFormat": {
+            "locale": "ja",
+            "pattern": "yyyy年MM月"
+        }
+    }
+}
+```
+
+## RTL Support
+
+### Enabling RTL
+
+```javascript
+import { setRTL } from 'visualify';
+
+// Enable RTL layout
+setRTL(true);
+
+// Or in configuration
+{
+    "i18n": {
+        "locale": "ar",
+        "rtl": true
+    }
+}
+```
+
+### RTL-Aware Components
+
+When RTL is enabled:
+- Charts flip horizontally
+- Legends align to the right
+- Tooltips adjust position
+- Axis labels reverse order
+
+## Loading Language Packs
+
+### Dynamic Loading
+
+```javascript
+import { loadLanguage } from 'visualify';
+
+// Load language pack on demand
+async function switchLanguage(lang) {
+    await loadLanguage(lang);
+    setLanguage(lang);
+}
+
+// Usage
+switchLanguage('es');  // Loads Spanish pack
+```
+
+### Bundling Languages
+
+```javascript
+// Import specific language packs
+import 'visualify/locales/zh-CN';
+import 'visualify/locales/ja';
+
+// Now available
+setLanguage('zh-CN');
+```
+
+## React Integration
+
+### useTranslation Hook
+
+```javascript
+import { useTranslation } from 'visualify';
+
+function MyChart() {
+    const { t, locale, setLocale } = useTranslation();
+
+    return (
+        <div>
+            <h1>{t('chart.title')}</h1>
+            <select
+                value={locale}
+                onChange={(e) => setLocale(e.target.value)}
+            >
+                <option value="en">English</option>
+                <option value="zh-CN">中文</option>
+            </select>
+        </div>
+    );
+}
+```
+
+### Language Switcher Component
+
+```javascript
+import { LanguageSwitcher } from 'visualify';
+
+function App() {
+    return (
+        <LanguageSwitcher
+            languages={['en', 'zh-CN', 'ja', 'es']}
+            onChange={(lang) => console.log('Switched to:', lang)}
+        />
+    );
+}
+```
+
+## Pluralization
+
+### Handling Plurals
+
+```javascript
+import { pluralize } from 'visualify';
+
+// Define plural forms
+addTranslations('en', {
+    'items.zero': 'No items',
+    'items.one': 'One item',
+    'items.other': '{{count}} items'
+});
+
+// Usage
+pluralize('items', 0);   // "No items"
+pluralize('items', 1);   // "One item"
+pluralize('items', 5);   // "5 items"
+```
+
+## Best Practices
+
+1. **Use translation keys** - Avoid hardcoded strings
+2. **Provide fallbacks** - Always have English as fallback
+3. **Test RTL layouts** - Verify Arabic/Hebrew rendering
+4. **Format numbers/dates** - Use locale-aware formatting
+5. **Lazy load languages** - Load only needed language packs
+
+## Creating Custom Language Packs
+
+### Structure
+
+```javascript
+// locales/custom-lang.js
+export default {
+    code: 'custom',
+    name: 'Custom Language',
+    rtl: false,
+    translations: {
+        'chart.title': 'Custom Title',
+        'chart.noData': 'No data',
+        // ... more keys
+    },
+    numberFormat: {
+        decimal: ',',
+        thousands: '.',
+        grouping: [3]
+    },
+    dateFormat: {
+        short: 'dd/MM/yyyy',
+        medium: 'dd MMM yyyy',
+        long: 'dd MMMM yyyy'
+    }
+};
+```
+
+### Registration
+
+```javascript
+import { registerLanguage } from 'visualify';
+import customLang from './locales/custom-lang';
+
+registerLanguage(customLang);
+```

package/docs/docs/log.md

@@ -1,9 +1,30 @@
-# log
-
-## 2.5.3-1(2024-02-24)
-
-### Features
-1. Scatter examples added.
-2. xAxis and yAxis now support Object type data.
-
-
+# log
+
+## 3.0.0 (2026-02-19)
+
+### Features
+1. Bundle splitting: separate core, 3D, and pages chunks for on-demand loading.
+2. CDN loader (`visualify-loader.js`): auto-loads echarts/plotly/three.js from CDN — single `<script>` tag usage.
+3. 3D visualization support: Scatter3D, Bar3D, Surface3D, Line3D via ECharts GL and Three.js.
+4. Internationalization (i18n): 6 languages with RTL support.
+5. Accessibility (a11y): keyboard navigation, ARIA labels, screen reader support.
+6. Live code editor with real-time chart preview.
+7. TypeScript configuration support with validation.
+
+### Optimizations
+1. Legacy IIFE bundle reduced from 9.6 MB to 1.8 MB by externalizing echarts, plotly, and three.js.
+2. Removed debug `console.log` statements from production code.
+3. Suppressed i18next default logger warnings.
+
+### Bug Fixes
+1. Fixed infinite re-render loop caused by unstable useEffect dependencies.
+2. Fixed Visium background image and visualMap coloring.
+3. Stabilized React component keys to prevent double event binding.
+
+## 2.5.3-1(2024-02-24)
+
+### Features
+1. Scatter examples added.
+2. xAxis and yAxis now support Object type data.
+
+

package/docs/docs/more-pages.md

@@ -1,23 +1,23 @@
-# More pages
-
-If you need more pages, you can simply create more `json` configuration files in
-your visualify directory. If you create a file named `scatter`, then it is
-accessible via `/scatter`.
-
-For example, the directory structure is as follows:
-
-```text
-.
-└── docs
-    ├── index.html
-    ├── scatter.json
-    └── honme.json
-```
-
-Matching routes
-
-```text
-docs/home.json        => http://domain.com
-                      => http://domain.com/home
-docs/scatter.json     => http://domain.com/scatter
-```
+# More pages
+
+If you need more pages, you can simply create more `json` configuration files in
+your visualify directory. If you create a file named `scatter`, then it is
+accessible via `/scatter`.
+
+For example, the directory structure is as follows:
+
+```text
+.
+└── docs
+    ├── index.html
+    ├── scatter.json
+    └── honme.json
+```
+
+Matching routes
+
+```text
+docs/home.json        => http://domain.com
+                      => http://domain.com/home
+docs/scatter.json     => http://domain.com/scatter
+```