@orbcharts/core 3.0.6 → 4.0.0-pre-alpha.0

package/src/utils/dom-lifecycle.ts

@@ -0,0 +1,164 @@
+/**
+ * DOM 元素生命週期管理工具
+ * 提供類似 D3.js 的 enter/update/exit 模式
+ */
+
+/**
+ * 比較兩個數組是否相等
+ */
+export function arraysEqual<T>(a: T[], b: T[]): boolean {
+  if (a.length !== b.length) return false
+  return a.every((val, i) => val === b[i])
+}
+
+/**
+ * 高效的元素重新排序函數，使用最少的 DOM 操作
+ */
+export function reorderElements<T extends Element>(
+  parent: Element, 
+  targetOrder: string[], 
+  elementsRef: Record<string, T>
+): void {
+  // 獲取當前所有相關的子元素
+  const currentElements = targetOrder
+    .map(name => elementsRef[name])
+    .filter(el => el && el.parentNode === parent)
+
+  if (currentElements.length === 0) return
+
+  // 檢查當前順序是否已經正確
+  let isCorrectOrder = true
+  let previousElement: Element | null = null
+  
+  for (const element of currentElements) {
+    if (previousElement && previousElement.nextElementSibling !== element) {
+      isCorrectOrder = false
+      break
+    }
+    previousElement = element
+  }
+
+  // 如果順序已經正確，直接返回
+  if (isCorrectOrder) return
+
+  // 使用 DocumentFragment 來批量操作，減少 reflow
+  const fragment = document.createDocumentFragment()
+  
+  // 按照目標順序將元素添加到 fragment
+  targetOrder.forEach(name => {
+    const element = elementsRef[name]
+    if (element && element.parentNode === parent) {
+      fragment.appendChild(element)
+    }
+  })
+  
+  // 一次性將所有元素插入回父元素
+  parent.appendChild(fragment)
+}
+
+/**
+ * 元素工廠函數類型
+ */
+export type ElementFactory<T extends Element> = (id: string) => T
+
+/**
+ * 生命週期鉤子函數類型
+ */
+export interface LifecycleHooks<T extends Element> {
+  /** 元素進入時的回調 */
+  onEnter?: (element: T, id: string) => void
+  /** 元素更新時的回調 */
+  onUpdate?: (element: T, id: string) => void
+  /** 元素退出前的回調 */
+  onExit?: (element: T, id: string) => void
+}
+
+/**
+ * D3.js 風格的元素生命週期管理：處理 enter/update/exit
+ * 
+ * @param parent 父容器元素
+ * @param targetIds 目標元素 ID 列表（按順序）
+ * @param elementsRef 元素引用字典
+ * @param createElement 元素創建工廠函數
+ * @param hooks 生命週期鉤子函數（可選）
+ */
+export function handleElementLifecycle<T extends Element>(
+  parent: Element,
+  targetIds: string[],
+  elementsRef: Record<string, T>,
+  createElement: ElementFactory<T>,
+  hooks?: LifecycleHooks<T>
+): void {
+  // Exit: 移除不再需要的元素
+  const currentIds = Object.keys(elementsRef)
+  const toRemove = currentIds.filter(id => !targetIds.includes(id))
+  
+  toRemove.forEach(id => {
+    const element = elementsRef[id]
+    if (element && element.parentNode === parent) {
+      // 執行退出回調
+      hooks?.onExit?.(element, id)
+      
+      // 從 DOM 移除
+      parent.removeChild(element)
+    }
+    delete elementsRef[id]
+  })
+
+  // Enter: 創建新元素
+  const toAdd = targetIds.filter(id => !elementsRef[id])
+  
+  toAdd.forEach(id => {
+    const element = createElement(id)
+    elementsRef[id] = element
+    parent.appendChild(element)
+    
+    // 執行進入回調
+    hooks?.onEnter?.(element, id)
+  })
+
+  // Update: 處理已存在的元素
+  const existing = targetIds.filter(id => elementsRef[id] && !toAdd.includes(id))
+  existing.forEach(id => {
+    const element = elementsRef[id]
+    hooks?.onUpdate?.(element, id)
+  })
+
+  // 重新排序所有存在的元素
+  if (targetIds.length > 0) {
+    reorderElements(parent, targetIds, elementsRef)
+  }
+}
+
+// /**
+//  * 創建 SVG group 元素的工廠函數
+//  */
+// export function createSVGGroup(className?: string): ElementFactory<SVGGElement> {
+//   return (id: string) => {
+//     const g = document.createElementNS('http://www.w3.org/2000/svg', 'g')
+//     g.classList.add(className ? `${className}--${id}` : `layer--${id}`)
+//     return g
+//   }
+// }
+
+// /**
+//  * 創建 Canvas 元素的工廠函數
+//  */
+// export function createCanvas(className?: string): ElementFactory<HTMLCanvasElement> {
+//   return (id: string) => {
+//     const canvas = document.createElement('canvas')
+//     canvas.classList.add(className ? `${className}--${id}` : `layer--${id}`)
+//     return canvas
+//   }
+// }
+
+// /**
+//  * 創建通用 DIV 元素的工廠函數
+//  */
+// export function createDiv(className?: string): ElementFactory<HTMLDivElement> {
+//   return (id: string) => {
+//     const div = document.createElement('div')
+//     div.classList.add(className ? `${className}--${id}` : `layer--${id}`)
+//     return div
+//   }
+// }

package/src/utils/dom.ts

@@ -0,0 +1,55 @@
+import { isDom } from "./commonUtils";
+
+export function createSVG (className?: string): SVGSVGElement {
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
+  svg.setAttribute('xmlns:xlink', 'http://www.w3.org/1999/xlink')
+  svg.setAttribute('xmls', 'http://www.w3.org/2000/svg')
+  svg.setAttribute('version', '1.1')
+  svg.style.position = 'absolute'
+  if (className) {
+    svg.classList.add(className)
+  }
+  return svg
+}
+
+export function createCanvasElement (className?: string): HTMLCanvasElement {
+  const canvas = document.createElement('canvas')
+  canvas.style.position = 'absolute'
+  if (className) {
+    canvas.classList.add(className)
+  }
+  return canvas
+}
+
+export function createSVGGroup(className?: string): SVGGElement {
+  const g = document.createElementNS('http://www.w3.org/2000/svg', 'g')
+  if (className) {
+    g.classList.add(className)
+  }
+  return g
+}
+
+export function createCanvas(className?: string): HTMLCanvasElement {
+  const canvas = document.createElement('canvas')
+  if (className) {
+    canvas.classList.add(className)
+  }
+  return canvas
+}
+
+export function createDiv(className?: string): HTMLDivElement {
+  const div = document.createElement('div')
+  if (className) {
+    div.classList.add(className)
+  }
+  return div
+}
+
+// 清空 element 底下所有元素
+export function removeElementChildren(el: HTMLElement | Element) {
+  if (isDom(el)) {
+    while (el.firstChild) {
+      el.removeChild(el.firstChild)
+    }
+  }
+}

package/src/utils/errorMessage.ts

@@ -1,41 +1,41 @@
-// message的prefix - error: 有中斷，warning: 無中斷
-export function createMessagePrefix (status: 'warning' | 'error'): string {
-  return `[OrbCharts ${status}]:`
-}
-
-// throw到最外層的錯誤訊息
-export function createOrbChartsErrorMessage (e: Error): string {
-  return `${createMessagePrefix('error')} ${e.message}`
-}
-
-
-// 未預期的錯誤
-export function createUnexpectedErrorMessage ({ from, systemMessage }: {
-  from: string // 
-  systemMessage: string // catch 給的的原生錯誤訊息
-}): string {
-  return `unexpected error from '${from}':
-${systemMessage}`
-}
-
-// validator 的 error 訊息
-export function createValidatorErrorMessage ({ columnName, expectToBe, from }: {
-  columnName: string // e.g. 'seriesLabels'
-  expectToBe: string // e.g. 'string[]'
-  from: string // e.g. Chart.chartParams$, Pie.params$
-}): string {
-  return `Invalid value: '${columnName}' must be '${expectToBe}'
-
-----> find in '${from}'`
-}
-
-// validator 的 warning 訊息
-export function createValidatorWarningMessage ({ columnName, expectToBe, from }: {
-  columnName: string // e.g. 'seriesLabels'
-  expectToBe: string // e.g. 'string[]'
-  from: string // e.g. Chart.chartParams$, Pie.params$
-}): string {
-  return `${createMessagePrefix('warning')} Value is not correct: '${columnName}' suppose to be '${expectToBe}', it may cause unexpected errors.'
-  
-----> find in '${from}'`
+// message的prefix - error: 有中斷，warning: 無中斷
+export function createMessagePrefix (status: 'warning' | 'error'): string {
+  return `[OrbCharts ${status}]:`
+}
+
+// throw到最外層的錯誤訊息
+export function createOrbChartsErrorMessage (e: Error): string {
+  return `${createMessagePrefix('error')} ${e.message}`
+}
+
+
+// 未預期的錯誤
+export function createUnexpectedErrorMessage ({ from, systemMessage }: {
+  from: string // 
+  systemMessage: string // catch 給的的原生錯誤訊息
+}): string {
+  return `unexpected error from '${from}':
+${systemMessage}`
+}
+
+// validator 的 error 訊息
+export function createValidatorErrorMessage ({ columnName, expectToBe, from }: {
+  columnName: string // e.g. 'seriesLabels'
+  expectToBe: string // e.g. 'string[]'
+  from: string // e.g. Chart.chartParams$, Pie.params$
+}): string {
+  return `Invalid value: '${columnName}' must be '${expectToBe}'
+
+----> find in '${from}'`
+}
+
+// validator 的 warning 訊息
+export function createValidatorWarningMessage ({ columnName, expectToBe, from }: {
+  columnName: string // e.g. 'seriesLabels'
+  expectToBe: string // e.g. 'string[]'
+  from: string // e.g. Chart.chartParams$, Pie.params$
+}): string {
+  return `${createMessagePrefix('warning')} Value is not correct: '${columnName}' suppose to be '${expectToBe}', it may cause unexpected errors.'
+  
+----> find in '${from}'`
 }

package/src/utils/index.ts

@@ -1,4 +1,8 @@
-export * from './commonUtils'
-export * from './d3Scale'
-export * from './observables'
-export * from './orbchartsUtils'
+export * from './aggregateUtils'
+export * from './colorUtils'
+export * from './commonUtils'
+export * from './dom'
+export * from './errorMessage'
+export * from './observables'
+export * from './orbchartsUtils'
+export * from './validator'

package/src/utils/observables.ts

@@ -1,309 +1,17 @@
-import {
-  combineLatest,
-  distinctUntilChanged,
-  filter,
-  map,
-  merge,
-  takeUntil,
-  shareReplay,
-  switchMap,
-  Subject,
-  Observable } from 'rxjs'
-import type {
-  ChartType,
-  ChartParams,
-  ComputedDatumBase,
-  ComputedDataTypeMap,
-  ComputedDatumTypeMap,
-  ContainerPositionScaled,
-  DataFormatterContainer,
-  DataFormatterTypeMap,
-  EventTypeMap,
-  HighlightTarget,
-  Layout,
-  TransformData } from '../../lib/core-types'
-
-// interface DatumUnknown {
-//   value: number | null
-//   id: string
-//   // label: string
-//   seriesLabel?: string // 要符合每一種computedData所以不一定會有seriesLabel
-//   groupLabel?: string // 要符合每一種computedData所以不一定會有groupLabel
-// }
-
-export function resizeObservable(elem: HTMLElement | Element): Observable<DOMRectReadOnly> {
-  return new Observable(subscriber => {
-    const ro = new ResizeObserver(entries => {
-      const entry = entries[0]
-      if (entry && entry.contentRect) {
-        subscriber.next(entry.contentRect)
-      }
-    })
-
-    ro.observe(elem)
-    return function unsubscribe() {
-      ro.unobserve(elem)
-    }
-  })
-}
-
-interface HighlightTargetValue {
-  id: string | null
-  label: string | null
-  seriesLabel: string | null
-  groupLabel: string | null
-  categoryLabel: string | null
-  highlightDefault: string | null
-}
-
-// 通用 highlight Observable
-export const highlightObservable = <T extends ChartType, D>({ datumList$, fullChartParams$, event$ }: {
-  datumList$: Observable<D[]>
-  fullChartParams$: Observable<ChartParams>
-  event$: Subject<EventTypeMap<T>>
-}): Observable<D[]> => {
-  const destroy$ = new Subject()
-
-  // 預設的highlight
-  const highlightDefault$: Observable<HighlightTargetValue> = fullChartParams$.pipe(
-    takeUntil(destroy$),
-    map(d => d.highlightDefault),
-    distinctUntilChanged(),
-    map(highlightDefault => {
-      return {
-        id: null,
-        label: null,
-        seriesLabel: null,
-        groupLabel: null,
-        categoryLabel: null,
-        highlightDefault
-      } as HighlightTargetValue
-    }),
-    shareReplay(1)
-  )
-
-  const highlightTarget$: Observable<HighlightTarget> = fullChartParams$.pipe(
-    takeUntil(destroy$),
-    map(d => d.highlightTarget),
-    distinctUntilChanged(),
-    shareReplay(1)
-  )
-
-  // 事件觸發的highlight
-  const highlightMouseover$: Observable<HighlightTargetValue> = highlightTarget$.pipe(
-    switchMap(highlightTarget => {
-      return event$.pipe(
-        takeUntil(destroy$),
-        // filter(d => d.eventName === 'mouseover' || d.eventName === 'mousemove'),
-        filter(d => d.eventName === 'mouseover'),
-        // distinctUntilChanged((prev, current) => prev.eventName === current.eventName)
-        map(_d => {
-          const d = _d as any
-          return d.datum
-            ? {
-              id: d.datum.id,
-              label: null, // label有可能重覆所以不做判斷
-              seriesLabel: highlightTarget === 'series' ? d.datum.seriesLabel : null,
-              groupLabel: highlightTarget === 'group' ? d.datum.groupLabel : null,
-              categoryLabel: highlightTarget === 'category' ? d.datum.categoryLabel : null,
-              highlightDefault: null
-            } as HighlightTargetValue
-            : {
-              id: null,
-              label: null,
-              seriesLabel: null,
-              groupLabel: null,
-              categoryLabel: null,
-              highlightDefault: null
-            } as HighlightTargetValue
-        })
-      )
-    })
-  )
-
-  const highlightMouseout$ = event$.pipe(
-    takeUntil(destroy$),
-    filter(d => d.eventName === 'mouseout'),
-    // distinctUntilChanged((prev, current) => prev.eventName === current.eventName)
-    // map(d => {
-    //   return { id: '', label: '' }
-    // })
-    switchMap(d => highlightDefault$)
-  )
-
-  // function getDatumIds (datumList: ComputedDatumTypeMap<T>[], id: string | null) {
-  //   const datum = datumList.find(d => (d as ComputedDatumBase).id === id)
-  //   return datum ? [datum] : []
-  // }
-  function getDatumIds (datumList: ComputedDatumTypeMap<T>[], id: string | null, label: string | null) {
-    return id == null && label == null
-      ? []
-      : datumList.filter(d => (d as ComputedDatumBase).id === id || (d as ComputedDatumBase).label === label)
-  }
-
-  function getSeriesIds (datumList: ComputedDatumTypeMap<T>[], seriesLabel: string | null) {
-    return seriesLabel == null
-      ? []
-      : datumList.filter(d => (d as ComputedDatumTypeMap<"series">).seriesLabel === seriesLabel)
-  }
-
-  function getGroupIds (datumList: ComputedDatumTypeMap<T>[], groupLabel: string | null) {
-    return groupLabel == null
-      ? []
-      : datumList.filter(d => (d as ComputedDatumTypeMap<"grid">).groupLabel === groupLabel)
-  }
-
-  function getCategoryIds (datumList: ComputedDatumTypeMap<T>[], categoryLabel: string | null) {
-    return categoryLabel == null
-      ? []
-      : datumList.filter(d => (d as ComputedDatumTypeMap<"multiValue" | "relationship" | "tree">).categoryLabel === categoryLabel)
-  }
-
-  return new Observable<D[]>(subscriber => {
-    combineLatest({
-      target: merge(highlightMouseover$, highlightMouseout$, highlightDefault$),
-      datumList: datumList$,
-      fullChartParams: fullChartParams$,
-    }).pipe(
-      takeUntil(destroy$),
-      switchMap(async d => d)
-    ).subscribe(data => {
-      let datumList: ComputedDatumTypeMap<T>[] = []
-      if (data.fullChartParams.highlightTarget === 'datum') {
-        datumList = getDatumIds(data.datumList as ComputedDatumTypeMap<T>[], data.target.id, data.target.label)
-      } else if (data.fullChartParams.highlightTarget === 'series') {
-        datumList = getSeriesIds(data.datumList as ComputedDatumTypeMap<T>[], data.target.seriesLabel)
-      } else if (data.fullChartParams.highlightTarget === 'group') {
-        datumList = getGroupIds(data.datumList as ComputedDatumTypeMap<T>[], data.target.groupLabel)
-      } else if (data.fullChartParams.highlightTarget === 'category') {
-        datumList = getCategoryIds(data.datumList as ComputedDatumTypeMap<T>[], data.target.categoryLabel)
-      }
-      
-      subscriber.next(datumList as D[])
-    })
-
-    return function unsubscribe () {
-      destroy$.next(undefined)
-    }
-  })
-}
-
-export const seriesDataMapObservable = <DatumType extends ComputedDatumTypeMap<'series' | 'grid'>>({ datumList$ }: { datumList$: Observable<DatumType[]> }) => {
-  return datumList$.pipe(
-    map(data => {
-      const SeriesDataMap: Map<string, DatumType[]> = new Map()
-      data.forEach(d => {
-        const seriesData = SeriesDataMap.get(d.seriesLabel) ?? []
-        seriesData.push(d)
-        SeriesDataMap.set(d.seriesLabel, seriesData)
-      })
-      return SeriesDataMap
-    })
-  )
-}
-
-export const groupDataMapObservable = <DatumType extends ComputedDatumTypeMap<'grid'>> ({ datumList$ }: { datumList$: Observable<DatumType[]> }) => {
-  return datumList$.pipe(
-    map(data => {
-      const GroupDataMap: Map<string, DatumType[]> = new Map()
-      data.forEach(d => {
-        const groupData = GroupDataMap.get(d.groupLabel) ?? []
-        groupData.push(d)
-        GroupDataMap.set(d.groupLabel, groupData)
-      })
-      return GroupDataMap
-    })
-  )
-}
-
-export const categoryDataMapObservable = <DatumType extends ComputedDatumTypeMap<'multiValue' | 'relationship' | 'tree'>> ({ datumList$ }: { datumList$: Observable<DatumType[]> }) => {
-  return datumList$.pipe(
-    map(data => {
-      const GroupDataMap: Map<string, DatumType[]> = new Map()
-      data
-        .filter(d => d.categoryLabel != null)
-        .forEach(d => {
-          const groupData = GroupDataMap.get(d.categoryLabel) ?? []
-          groupData.push(d)
-          GroupDataMap.set(d.categoryLabel, groupData)
-        })
-      return GroupDataMap
-    })
-  )
-}
-
-export const textSizePxObservable = (chartParams$: Observable<ChartParams>) => {
-  return chartParams$.pipe(
-    map(d => d.styles.textSize),
-    distinctUntilChanged(),
-    map(data => {
-      let value = NaN
-      if (typeof data === 'string') {
-        if (data.includes('rem')) {
-          const rootFontSizePx = parseFloat(getComputedStyle(document.documentElement).fontSize)
-          const num = parseFloat(data)
-          value = num * rootFontSizePx
-        } else if (data.includes('px')) {
-          value = parseFloat(data)
-        }
-      } else if (typeof data === 'number') {
-        return data
-      }
-      return value ? value : 14 // default
-    })
-  )
-}
-
-export const containerSizeObservable = ({ layout$, containerPosition$, container$ }: {
-  layout$: Observable<Layout>
-  containerPosition$: Observable<ContainerPositionScaled[]>
-  container$: Observable<DataFormatterContainer>
-}) => {
-  const rowAmount$ = containerPosition$.pipe(
-    map(containerPosition => {
-      const maxRowIndex = containerPosition.reduce((acc, current) => {
-        return current.rowIndex > acc ? current.rowIndex : acc
-      }, 0)
-      return maxRowIndex + 1
-    }),
-    distinctUntilChanged(),
-  )
-
-  const columnAmount$ = containerPosition$.pipe(
-    map(containerPosition => {
-      const maxColumnIndex = containerPosition.reduce((acc, current) => {
-        return current.columnIndex > acc ? current.columnIndex : acc
-      }, 0)
-      return maxColumnIndex + 1
-    }),
-    distinctUntilChanged()
-  )
-
-  return combineLatest({
-    layout: layout$,
-    rowAmount: rowAmount$,
-    columnAmount: columnAmount$,
-    container: container$
-  }).pipe(
-    switchMap(async (d) => d),
-    map(data => {
-      // const width = (data.layout.rootWidth / data.columnAmount) - (data.layout.left + data.layout.right)
-      // const height = (data.layout.rootHeight / data.rowAmount) - (data.layout.top + data.layout.bottom)
-      const columnGap = data.container.columnGap === 'auto'
-        ? data.layout.left + data.layout.right
-        : data.container.columnGap
-      const rowGap = data.container.rowGap === 'auto'
-        ? data.layout.top + data.layout.bottom
-        : data.container.rowGap
-      const width = (data.layout.rootWidth - data.layout.left - data.layout.right - (columnGap * (data.columnAmount - 1))) / data.columnAmount
-      const height = (data.layout.rootHeight - data.layout.top - data.layout.bottom - (rowGap * (data.rowAmount - 1))) / data.rowAmount
-      
-      return {
-        width,
-        height
-      }
-    }),
-    distinctUntilChanged((a, b) => a.width === b.width && a.height === b.height),
-    // shareReplay(1)
-  )
+import { Observable, BehaviorSubject } from 'rxjs'
+
+export function resizeObservable(elem: HTMLElement | Element): Observable<DOMRectReadOnly> {
+  return new Observable(subscriber => {
+    const ro = new ResizeObserver(entries => {
+      const entry = entries[0]
+      if (entry && entry.contentRect) {
+        subscriber.next(entry.contentRect)
+      }
+    })
+
+    ro.observe(elem)
+    return function unsubscribe() {
+      ro.unobserve(elem)
+    }
+  })
 }