@pyreon/charts 0.6.0

package/src/tests/charts.test.tsx

@@ -0,0 +1,363 @@
+import { mount } from '@pyreon/runtime-dom'
+import { Chart } from '../chart-component'
+import {
+  _resetLoader,
+  ensureModules,
+  getCore,
+  getCoreSync,
+  manualUse,
+} from '../loader'
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function mountWith<T>(fn: () => T): { result: T; unmount: () => void } {
+  let result: T | undefined
+  const el = document.createElement('div')
+  document.body.appendChild(el)
+  const Child = () => {
+    result = fn()
+    return null
+  }
+  const unmount = mount(<Child />, el)
+  return {
+    result: result!,
+    unmount: () => {
+      unmount()
+      el.remove()
+    },
+  }
+}
+
+afterEach(() => {
+  _resetLoader()
+})
+
+// ─── Loader ───────────────────────────────────────────────────────────────────
+
+describe('loader', () => {
+  it('lazily loads echarts/core on first call', async () => {
+    const core = await getCore()
+    expect(core).toBeDefined()
+    expect(typeof core.init).toBe('function')
+    expect(typeof core.use).toBe('function')
+  })
+
+  it('caches core module on subsequent calls', async () => {
+    const core1 = await getCore()
+    const core2 = await getCore()
+    expect(core1).toBe(core2)
+  })
+
+  it('auto-detects BarChart from series type', async () => {
+    const core = await ensureModules({
+      series: [{ type: 'bar', data: [1, 2, 3] }],
+    })
+    expect(core).toBeDefined()
+    // If it didn't throw, the modules were registered successfully
+  })
+
+  it('auto-detects PieChart from series type', async () => {
+    const core = await ensureModules({
+      series: [{ type: 'pie', data: [{ value: 1 }] }],
+    })
+    expect(core).toBeDefined()
+  })
+
+  it('auto-detects LineChart from series type', async () => {
+    const core = await ensureModules({
+      series: [{ type: 'line', data: [1, 2, 3] }],
+    })
+    expect(core).toBeDefined()
+  })
+
+  it('auto-detects components from config keys', async () => {
+    const core = await ensureModules({
+      tooltip: { trigger: 'axis' },
+      legend: {},
+      xAxis: { type: 'category' },
+      yAxis: { type: 'value' },
+      series: [{ type: 'bar', data: [1] }],
+    })
+    expect(core).toBeDefined()
+  })
+
+  it('auto-detects series features (markPoint, markLine, markArea)', async () => {
+    const core = await ensureModules({
+      series: [
+        {
+          type: 'line',
+          data: [1, 2, 3],
+          markPoint: { data: [{ type: 'max' }] },
+          markLine: { data: [{ type: 'average' }] },
+          markArea: { data: [[{ xAxis: 'A' }, { xAxis: 'B' }]] },
+        },
+      ],
+    })
+    expect(core).toBeDefined()
+  })
+
+  it('loads multiple chart types in one config', async () => {
+    const core = await ensureModules({
+      series: [
+        { type: 'bar', data: [1, 2] },
+        { type: 'line', data: [3, 4] },
+        { type: 'scatter', data: [[1, 2]] },
+      ],
+    })
+    expect(core).toBeDefined()
+  })
+
+  it('caches modules across calls', async () => {
+    // First call loads BarChart
+    await ensureModules({ series: [{ type: 'bar', data: [1] }] })
+    // Second call should be instant (cached)
+    const start = performance.now()
+    await ensureModules({ series: [{ type: 'bar', data: [2] }] })
+    const duration = performance.now() - start
+    // Should be near-instant since modules are cached
+    expect(duration).toBeLessThan(50)
+  })
+
+  it('handles series as single object (not array)', async () => {
+    const core = await ensureModules({
+      series: { type: 'bar', data: [1, 2, 3] },
+    })
+    expect(core).toBeDefined()
+  })
+
+  it('handles empty series gracefully', async () => {
+    const core = await ensureModules({ series: [] })
+    expect(core).toBeDefined()
+  })
+
+  it('handles config with no series', async () => {
+    const core = await ensureModules({ title: { text: 'Hello' } })
+    expect(core).toBeDefined()
+  })
+
+  it('ignores unknown chart types', async () => {
+    const core = await ensureModules({
+      series: [{ type: 'nonexistent', data: [1] }],
+    })
+    expect(core).toBeDefined()
+  })
+
+  it('loads SVG renderer when specified', async () => {
+    const core = await ensureModules(
+      { series: [{ type: 'bar', data: [1] }] },
+      'svg',
+    )
+    expect(core).toBeDefined()
+  })
+
+  it('resets state with _resetLoader', async () => {
+    await getCore() // load core
+    _resetLoader()
+    // After reset, core should be null internally but getCore still works
+    const core = await getCore()
+    expect(core).toBeDefined()
+  })
+
+  it('getCoreSync returns null before loading', () => {
+    _resetLoader()
+    expect(getCoreSync()).toBeNull()
+  })
+
+  it('getCoreSync returns core after loading', async () => {
+    await getCore()
+    expect(getCoreSync()).not.toBeNull()
+    expect(typeof getCoreSync()!.init).toBe('function')
+  })
+
+  it('manualUse registers modules when core is loaded', async () => {
+    await getCore() // ensure core is loaded
+    // Should not throw — registers module with core.use()
+    const { CanvasRenderer } = await import('echarts/renderers')
+    expect(() => manualUse(CanvasRenderer)).not.toThrow()
+  })
+
+  it('manualUse queues modules when core is not yet loaded', async () => {
+    _resetLoader()
+    // Core not loaded yet — should queue, not throw
+    const { CanvasRenderer } = await import('echarts/renderers')
+    expect(() => manualUse(CanvasRenderer)).not.toThrow()
+  })
+
+  it('loads radar component for radar config key', async () => {
+    const core = await ensureModules({
+      radar: { indicator: [{ name: 'A' }] },
+      series: [{ type: 'radar', data: [{ value: [1] }] }],
+    })
+    expect(core).toBeDefined()
+  })
+})
+
+// ─── Chart component ─────────────────────────────────────────────────────────
+
+describe('Chart component', () => {
+  it('renders a div element', () => {
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+
+    const unmount = mount(
+      <Chart
+        options={() => ({
+          series: [{ type: 'bar', data: [1, 2, 3] }],
+        })}
+        style="height: 300px"
+      />,
+      container,
+    )
+
+    const div = container.querySelector('div')
+    expect(div).not.toBeNull()
+
+    unmount()
+    container.remove()
+  })
+
+  it('applies style and class props to container', () => {
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+
+    const unmount = mount(
+      <Chart
+        options={() => ({
+          series: [{ type: 'bar', data: [1] }],
+        })}
+        style="height: 400px; width: 100%"
+        class="revenue-chart"
+      />,
+      container,
+    )
+
+    const div = container.querySelector('div')
+    expect(div?.getAttribute('style')).toContain('height: 400px')
+    expect(div?.getAttribute('class')).toContain('revenue-chart')
+
+    unmount()
+    container.remove()
+  })
+})
+
+// ─── useChart basic API ──────────────────────────────────────────────────────
+
+describe('useChart API', () => {
+  // Import useChart lazily to avoid module-level echarts import issues
+  it('returns the correct shape', async () => {
+    const { useChart } = await import('../use-chart')
+
+    const { result: chart, unmount } = mountWith(() =>
+      useChart(() => ({
+        series: [{ type: 'bar', data: [1, 2, 3] }],
+      })),
+    )
+
+    expect(typeof chart.ref).toBe('function')
+    expect(chart.instance()).toBeNull()
+    expect(chart.loading()).toBe(true)
+    expect(typeof chart.resize).toBe('function')
+
+    unmount()
+  })
+
+  it('resize does not throw when no instance', async () => {
+    const { useChart } = await import('../use-chart')
+
+    const { result: chart, unmount } = mountWith(() =>
+      useChart(() => ({
+        series: [{ type: 'bar', data: [1] }],
+      })),
+    )
+
+    expect(() => chart.resize()).not.toThrow()
+    unmount()
+  })
+
+  it('loading starts as true', async () => {
+    const { useChart } = await import('../use-chart')
+
+    const { result: chart, unmount } = mountWith(() =>
+      useChart(() => ({
+        series: [{ type: 'pie', data: [{ value: 1 }] }],
+      })),
+    )
+
+    expect(chart.loading()).toBe(true)
+    unmount()
+  })
+})
+
+// ─── All supported chart types ──────────────────────────────────────────────
+
+describe('supported chart types', () => {
+  const chartTypes = [
+    'bar',
+    'line',
+    'pie',
+    'scatter',
+    'radar',
+    'heatmap',
+    'treemap',
+    'sunburst',
+    'sankey',
+    'funnel',
+    'gauge',
+    'graph',
+    'tree',
+    'boxplot',
+    'candlestick',
+    'parallel',
+    'themeRiver',
+    'effectScatter',
+    'lines',
+    'pictorialBar',
+    'custom',
+    'map',
+  ]
+
+  for (const type of chartTypes) {
+    it(`loads modules for type: ${type}`, async () => {
+      _resetLoader()
+      const core = await ensureModules({
+        series: [{ type, data: [1] }],
+      })
+      expect(core).toBeDefined()
+    })
+  }
+})
+
+// ─── All supported component keys ───────────────────────────────────────────
+
+describe('supported component keys', () => {
+  const componentKeys = [
+    'tooltip',
+    'legend',
+    'title',
+    'toolbox',
+    'dataZoom',
+    'visualMap',
+    'timeline',
+    'graphic',
+    'brush',
+    'calendar',
+    'dataset',
+    'aria',
+    'grid',
+    'xAxis',
+    'yAxis',
+    'polar',
+    'geo',
+  ]
+
+  for (const key of componentKeys) {
+    it(`loads component for config key: ${key}`, async () => {
+      _resetLoader()
+      const core = await ensureModules({
+        [key]: {},
+        series: [{ type: 'bar', data: [1] }],
+      })
+      expect(core).toBeDefined()
+    })
+  }
+})

package/src/types.ts

@@ -0,0 +1,118 @@
+import type { Props } from '@pyreon/core'
+import type { Signal } from '@pyreon/reactivity'
+import type { ComposeOption, EChartsOption, SetOptionOpts } from 'echarts'
+import type { ECharts } from 'echarts/core'
+
+// ─── Re-export ECharts types for consumer convenience ────────────────────────
+
+// Re-export series option types
+// Re-export component option types
+export type {
+  BarSeriesOption,
+  BoxplotSeriesOption,
+  CandlestickSeriesOption,
+  DataZoomComponentOption,
+  FunnelSeriesOption,
+  GaugeSeriesOption,
+  GraphSeriesOption,
+  GridComponentOption,
+  HeatmapSeriesOption,
+  LegendComponentOption,
+  LineSeriesOption,
+  PieSeriesOption,
+  RadarSeriesOption,
+  SankeySeriesOption,
+  ScatterSeriesOption,
+  SunburstSeriesOption,
+  TitleComponentOption,
+  ToolboxComponentOption,
+  TooltipComponentOption,
+  TreemapSeriesOption,
+  TreeSeriesOption,
+  VisualMapComponentOption,
+} from 'echarts'
+export type { ComposeOption, ECharts, EChartsOption, SetOptionOpts }
+
+// ─── Event types (duck-typed to avoid echarts dual-package type conflicts) ───
+
+/** Chart event params — duck-typed to work across echarts entry points */
+export interface ChartEventParams {
+  componentType?: string
+  seriesType?: string
+  seriesIndex?: number
+  seriesName?: string
+  name?: string
+  dataIndex?: number
+  data?: unknown
+  dataType?: string
+  value?: unknown
+  color?: string
+  event?: Event
+  [key: string]: unknown
+}
+
+// ─── Chart config ────────────────────────────────────────────────────────────
+
+/**
+ * Configuration for useChart.
+ */
+export interface UseChartConfig {
+  /** ECharts theme — 'dark', a registered theme name, or a theme object */
+  theme?: string | Record<string, unknown>
+  /** Renderer — 'canvas' (default, best performance) or 'svg' */
+  renderer?: 'canvas' | 'svg'
+  /** ECharts locale — 'EN' (default), 'ZH', etc. */
+  locale?: string
+  /** Whether to replace all options instead of merging — default: false */
+  notMerge?: boolean
+  /** Whether to batch updates — default: true */
+  lazyUpdate?: boolean
+  /** Device pixel ratio — default: window.devicePixelRatio */
+  devicePixelRatio?: number
+  /** Width override — default: container width */
+  width?: number
+  /** Height override — default: container height */
+  height?: number
+  /** Called when chart instance is created */
+  onInit?: (instance: ECharts) => void
+}
+
+/**
+ * Return type of useChart.
+ */
+export interface UseChartResult {
+  /** Bind to container element via ref */
+  ref: (el: Element | null) => void
+  /** The ECharts instance — null until mounted and modules loaded */
+  instance: Signal<ECharts | null>
+  /** True while ECharts modules are being dynamically imported */
+  loading: Signal<boolean>
+  /** Error signal — set if chart init or setOption throws */
+  error: Signal<Error | null>
+  /** Manually trigger resize */
+  resize: () => void
+}
+
+/**
+ * Props for the <Chart /> component.
+ * Generic parameter narrows the option type for exact autocomplete.
+ */
+export interface ChartProps<TOption extends EChartsOption = EChartsOption>
+  extends Props {
+  /** Reactive ECharts option config — fully typed */
+  options: () => TOption
+  /** ECharts theme */
+  theme?: string | Record<string, unknown>
+  /** Renderer — 'canvas' (default) or 'svg' */
+  renderer?: 'canvas' | 'svg'
+  /** CSS style for the container div */
+  style?: string
+  /** CSS class for the container div */
+  class?: string
+  /** Click event handler */
+  onClick?: (params: ChartEventParams) => void
+  /** Mouseover event handler */
+  onMouseover?: (params: ChartEventParams) => void
+  /** Mouseout event handler */
+  onMouseout?: (params: ChartEventParams) => void
+}

package/src/use-chart.ts

@@ -0,0 +1,136 @@
+import { onUnmount } from '@pyreon/core'
+import { effect, signal } from '@pyreon/reactivity'
+import type { EChartsOption } from 'echarts'
+import { ensureModules } from './loader'
+import type { UseChartConfig, UseChartResult } from './types'
+
+/**
+ * Reactive ECharts hook. Creates a chart instance bound to a container
+ * element, with automatic module lazy-loading, signal tracking, resize
+ * handling, error capture, and cleanup.
+ *
+ * Generic parameter `TOption` narrows the option type for exact autocomplete.
+ * Use `ComposeOption<SeriesUnion>` from ECharts to restrict to specific chart types.
+ *
+ * @example
+ * ```tsx
+ * // Default — accepts any ECharts option
+ * const chart = useChart(() => ({
+ *   series: [{ type: 'bar', data: revenue() }],
+ * }))
+ *
+ * // Strict — only bar + line allowed, full autocomplete
+ * import type { ComposeOption, BarSeriesOption, LineSeriesOption } from '@pyreon/charts'
+ * type MyChartOption = ComposeOption<BarSeriesOption | LineSeriesOption>
+ *
+ * const chart = useChart<MyChartOption>(() => ({
+ *   series: [{ type: 'bar', data: revenue() }],  // ✓
+ * }))
+ * ```
+ */
+export function useChart<TOption extends EChartsOption = EChartsOption>(
+  optionsFn: () => TOption,
+  config?: UseChartConfig,
+): UseChartResult {
+  const instance = signal<import('echarts/core').ECharts | null>(null)
+  const loading = signal(true)
+  const error = signal<Error | null>(null)
+  const container = signal<HTMLElement | null>(null)
+  const renderer = config?.renderer ?? 'canvas'
+
+  let observer: ResizeObserver | null = null
+  let initialized = false
+
+  // Initialize chart when container is bound
+  effect(() => {
+    const el = container()
+    if (!el || initialized) return
+
+    initialized = true
+
+    let opts: EChartsOption
+    try {
+      opts = optionsFn()
+    } catch (err) {
+      error.set(err instanceof Error ? err : new Error(String(err)))
+      loading.set(false)
+      return
+    }
+
+    // Load required ECharts modules, then create chart
+    ensureModules(opts as Record<string, unknown>, renderer)
+      .then((core) => {
+        // Guard: component may have unmounted during async load
+        if (!container.peek()) return
+
+        try {
+          const chart = core.init(el, config?.theme as any, {
+            renderer,
+            locale: config?.locale,
+            devicePixelRatio: config?.devicePixelRatio,
+            width: config?.width,
+            height: config?.height,
+          })
+
+          chart.setOption(opts)
+          instance.set(chart)
+          loading.set(false)
+          error.set(null)
+
+          config?.onInit?.(chart)
+
+          // ResizeObserver for auto-resize
+          observer = new ResizeObserver(() => {
+            chart.resize()
+          })
+          observer.observe(el)
+        } catch (err) {
+          error.set(err instanceof Error ? err : new Error(String(err)))
+          loading.set(false)
+        }
+      })
+      .catch((err) => {
+        error.set(err instanceof Error ? err : new Error(String(err)))
+        loading.set(false)
+      })
+  })
+
+  // Reactive updates — re-run when signals in optionsFn change
+  effect(() => {
+    const chart = instance()
+    if (!chart) return
+
+    try {
+      const opts = optionsFn()
+      chart.setOption(opts, {
+        notMerge: config?.notMerge ?? false,
+        lazyUpdate: config?.lazyUpdate ?? true,
+      })
+      error.set(null)
+    } catch (err) {
+      error.set(err instanceof Error ? err : new Error(String(err)))
+    }
+  })
+
+  // Cleanup on unmount
+  onUnmount(() => {
+    observer?.disconnect()
+    observer = null
+
+    const chart = instance.peek()
+    if (chart) {
+      chart.dispose()
+      instance.set(null)
+    }
+
+    initialized = false
+  })
+
+  return {
+    ref: (el: Element | null) => container.set(el as HTMLElement | null),
+    instance,
+    loading,
+    error,
+    resize: () => instance.peek()?.resize(),
+  }
+}