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

package/src/types/Plugin.ts

@@ -0,0 +1,98 @@
+import { Observable, Subject } from 'rxjs'
+import type {
+  DeepPartial,
+  LayerEntity,
+  ChartContext,
+  ExtendableContext
+} from './index'
+import { ValidatorResult } from '../types/Validator'
+
+
+export interface PluginInfo {
+  id: string
+  name: string
+  elementType: 'svg' | 'canvas'
+  shownLayers: string[]
+}
+
+// export interface PluginSetupProps<ExtendContext extends ExtendableContext, PluginParams extends Record<string, any>> {
+//   context: ChartContext<ExtendContext>
+//   svg: SVGElement
+//   canvas: HTMLCanvasElement
+//   pluginParams$: Observable<PluginParams>
+// }
+
+// export interface SVGPluginSetupProps<ExtendContext extends ExtendableContext, PluginParams extends Record<string, any>> {
+//   context: ChartContext<ExtendContext>
+//   svgG: SVGGElement
+//   pluginParams$: Observable<PluginParams>
+// }
+
+// export interface CanvasPluginSetupProps<ExtendContext extends ExtendableContext, PluginParams extends Record<string, any>> {
+//   context: ChartContext<ExtendContext>
+//   canvas: HTMLCanvasElement
+//   pluginParams$: Observable<PluginParams>
+// }
+
+// export type PluginSetupProps<ElementType extends 'svg' | 'canvas', ExtendContext extends ExtendableContext, PluginParams extends Record<string, any>> =
+//   ElementType extends 'svg' ? SVGPluginSetupProps<ExtendContext, PluginParams> :
+//   ElementType extends 'canvas' ? CanvasPluginSetupProps<ExtendContext, PluginParams> :
+//   never
+
+export interface PluginSetupProps<ExtendContext extends ExtendableContext, PluginParams extends Record<string, any>> {
+  context: ChartContext<ExtendContext>
+  pluginParams$: Observable<PluginParams>
+}
+
+export interface DefinePluginConfig<ExtendContext extends ExtendableContext, PluginParams extends Record<string, any>, AllLayerParams extends Record<string, any>>{
+  name: string
+  defaultParams?: PluginParams
+  validator?: (params: DeepPartial<AllLayerParams | PluginParams>) => ValidatorResult
+    // { valid: boolean; errors?: string[] }
+  layers?: LayerEntity<ExtendContext, PluginParams, AllLayerParams[keyof AllLayerParams]>[]
+  // extendContext?: (context: Readonly<ChartContext>) => ExtendContext
+  setup?: (props: PluginSetupProps<ExtendContext, PluginParams>) => () => void
+}
+
+// export interface CreatePlugin<PluginParams> {
+//   (config: DefinePluginConfig<PluginParams>): PluginEntity<PluginParams>
+// }
+
+
+export interface PluginEntity<ElementType extends 'svg' | 'canvas', PluginParams extends Record<string, any>, AllLayerParams extends Record<string, any>> {
+  readonly _name: string
+  readonly _elementType: ElementType
+  _getId: () => string
+  _setId: (id: string) => void
+  _injectContext(context: ChartContext<{}>): void
+  // layer visibility controls
+  show(names: (keyof AllLayerParams) | (keyof AllLayerParams)[]): void
+  showOnly(names: (keyof AllLayerParams) | (keyof AllLayerParams)[]): void
+  showAll(): void
+  hide(names: (keyof AllLayerParams) | (keyof AllLayerParams)[]): void
+  hideAll(): void
+  toggle(names: (keyof AllLayerParams) | (keyof AllLayerParams)[]): void
+  getShownLayerNames(): (keyof AllLayerParams)[]
+  // layer params
+  // setLayers(partial: DeepPartial<PluginParams>): void // deep-merge with default
+  updateParams(patch: DeepPartial<PluginParams | AllLayerParams>): void // deep-merge with previous
+  forceReplaceParams(full: PluginParams | AllLayerParams): void // replace（特殊需求，可節省效能）
+  getParams(): Readonly<PluginParams | AllLayerParams>
+  // layer<LayerName extends keyof PluginParams>(name: LayerName): {
+  //   // set(partial: DeepPartial<PluginParams[LayerName]>): void // deep-merge with default 該 layer 的 params
+  //   update(patch: DeepPartial<PluginParams[LayerName]>): void // deep-merge with previous 該 layer 的 params
+  //   replace(full: PluginParams[LayerName]): void // replace（特殊需求，可節省效能）
+  //   show(): void
+  //   hide(): void
+  //   toggle(): void
+  // }
+
+  destroy(): void
+
+  // outputs (observables)
+  // layers$: Observable<LayersConfig> // 各 layer 的有效參數（合併後）
+  // visibleLayerNames$: Observable<string[]> // 目前可見的 layer 清單（原 show$）
+  // event$: Observable<{ data: EventData; event: Event }> // 互動事件
+}
+
+

package/src/types/RawData.ts

@@ -0,0 +1,67 @@
+
+
+// RawData -> ModelData (DataEndoding & ModelType) -> RenderData (Plugin)
+
+
+
+export type RawData = RawDataColumn[] | RawDataColumn[][] // 二維陣列會轉化為多個dataset
+
+// 可透過 DataEncoding 更改欄位名稱的預設欄位
+export type DynamicDefaultRawDataFields = {
+  value?: number | null
+  x?: number | null // multivariate
+  y?: number | null // multivariate
+  z?: number | null // multivariate
+  dataset?: string
+  series?: string
+  category?: string
+}
+
+export type RawDataColumn<DynamicFields extends Record<string, any> = DynamicDefaultRawDataFields> = {
+  // 不可變更的基本欄位
+  id?: string
+  name?: string
+  source?: string
+  target?: string
+  parent?: string
+  data?: any
+} & DynamicFields // 可變更的欄位
+
+
+
+// export type DynamicRawDataColumn<
+//   ValueField extends string = 'value',
+//   DatasetField extends string = 'dataset', 
+//   SeriesField extends string = 'series',
+//   CategoryField extends string = 'category'
+// > = {
+//   id?: string
+//   name?: string
+//   source?: string
+//   target?: string
+//   parent?: string
+//   data?: any
+// } & {
+//   [K in ValueField]: number | null
+// } & {
+//   [K in DatasetField]?: string
+// } & {
+//   [K in SeriesField]?: string
+// } & {
+//   [K in CategoryField]?: string
+// }
+
+// export type FlexibleRawDataColumn<T extends Record<string, any> = {}> = {
+//   id?: string
+//   value?: number | null
+//   name?: string
+//   dataset?: string
+//   series?: string
+//   category?: string
+//   source?: string
+//   target?: string
+//   parent?: string
+//   data?: any
+// } & T
+
+

package/src/types/RenderData.ts

@@ -0,0 +1,16 @@
+import type {
+  ModelType,
+  ModelDatum,
+  ModelDatumGraphEdge
+} from './index'
+
+// 基礎型別，其他欄位留給 Plugin 擴充
+// export interface RenderDatumBase<T extends ModelType> {
+//   modelDatum: ModelDatum<T>
+// }
+export type RenderDatumBase<
+  T extends ModelType,
+  ExtendTypes extends Record<string, any> = {}
+> = ModelDatum<T> & ExtendTypes
+
+export type RenderDatumGraphEdge<ExtendTypes extends Record<string, any> = {}> = ModelDatumGraphEdge & ExtendTypes

package/src/types/Theme.ts

@@ -0,0 +1,21 @@
+
+export interface Colors {
+  data: string[],
+  primary: string,
+  secondary: string,
+  dataContrast: string[],
+  background: string
+}
+
+export type ColorScheme = 'light' | 'dark'
+
+export interface Theme {
+  colorScheme: ColorScheme | 'auto'
+  colors: {
+    light: Colors,
+    dark: Colors
+  },
+  fontSize: string | number
+}
+
+export type ColorType = 'none' | keyof Colors

package/src/types/Validator.ts

@@ -0,0 +1,36 @@
+export type ToBeTypes = 'string' | 'number' | 'boolean' | 'object' | 'object[]' | 'string[]' | 'number[]' | 'Function' | 'null' | 'undefined'
+
+export type ToBeOption = 'ColorType'
+
+// 有使用定義好的型別則不需寫 validate
+export interface ValidatorRuleToBeTypes {
+  toBeTypes: ToBeTypes[]
+}
+
+// 自訂規則
+export interface ValidatorRuleToBe {
+  toBe: string
+  test: (value: any) => boolean
+}
+
+// 選項資料型別
+export interface ValidatorRuleToBeOption {
+  toBeOption: ToBeOption
+}
+
+export type ValidatorRule<T> = {[key in keyof T]: ValidatorRuleToBeTypes | ValidatorRuleToBe | ValidatorRuleToBeOption}
+
+
+// export type ValidateObject<T> = (data: T, rules: ValidatorRule<T>) => ValidatorResult
+
+// export interface ValidatorUtils {
+//   validateObject: typeof validateObject // 我發現要這樣寫才能夠透過 data 型別自動推斷出 T，不曉得有沒有更好的寫法
+// }
+
+
+export interface ValidatorResult {
+  status: 'success' | 'warning' | 'error'
+  // message: string // warning or error message
+  columnName: string,
+  expectToBe: string,
+}

package/src/types/index.ts

@@ -0,0 +1,12 @@
+export * from './Chart'
+export * from './ChartContext'
+export * from './Encoding'
+export * from './Event'
+export * from './Layers'
+export * from './ModelData'
+export * from './Plugin'
+export * from './RawData'
+export * from './RenderData'
+export * from './Theme'
+export * from './Validator'
+export * from './Common'

package/src/utils/aggregateUtils.ts

@@ -0,0 +1,99 @@
+/**
+ * 聚合函數工具集
+ * 用於處理數值陣列的各種聚合運算
+ */
+
+export type AggregateType = 'sum' | 'mean' | 'median' | 'min' | 'max' | 'count' | 'none'
+
+/**
+ * 計算數值陣列的總和
+ */
+export function sum(values: (number | null)[]): number | null {
+  const validValues = values.filter((v): v is number => v !== null && !isNaN(v))
+  if (validValues.length === 0) return null
+  return validValues.reduce((acc, val) => acc + val, 0)
+}
+
+/**
+ * 計算數值陣列的平均值
+ */
+export function mean(values: (number | null)[]): number | null {
+  const validValues = values.filter((v): v is number => v !== null && !isNaN(v))
+  if (validValues.length === 0) return null
+  const total = validValues.reduce((acc, val) => acc + val, 0)
+  return total / validValues.length
+}
+
+/**
+ * 計算數值陣列的中位數
+ */
+export function median(values: (number | null)[]): number | null {
+  const validValues = values.filter((v): v is number => v !== null && !isNaN(v))
+  if (validValues.length === 0) return null
+  
+  const sorted = [...validValues].sort((a, b) => a - b)
+  const mid = Math.floor(sorted.length / 2)
+  
+  if (sorted.length % 2 === 0) {
+    return (sorted[mid - 1] + sorted[mid]) / 2
+  } else {
+    return sorted[mid]
+  }
+}
+
+/**
+ * 計算數值陣列的最小值
+ */
+export function min(values: (number | null)[]): number | null {
+  const validValues = values.filter((v): v is number => v !== null && !isNaN(v))
+  if (validValues.length === 0) return null
+  return Math.min(...validValues)
+}
+
+/**
+ * 計算數值陣列的最大值
+ */
+export function max(values: (number | null)[]): number | null {
+  const validValues = values.filter((v): v is number => v !== null && !isNaN(v))
+  if (validValues.length === 0) return null
+  return Math.max(...validValues)
+}
+
+/**
+ * 計算數值陣列的有效數量
+ */
+export function count(values: (number | null)[]): number {
+  return values.filter((v): v is number => v !== null && !isNaN(v)).length
+}
+
+/**
+ * 不進行聚合，返回第一個有效值
+ */
+export function none(values: (number | null)[]): number | null {
+  const validValues = values.filter((v): v is number => v !== null && !isNaN(v))
+  return validValues.length > 0 ? validValues[0] : null
+}
+
+/**
+ * 根據聚合類型執行對應的聚合函數
+ */
+export function aggregate(values: (number | null)[], type: AggregateType): number | null {
+  switch (type) {
+    case 'sum':
+      return sum(values)
+    case 'mean':
+      return mean(values)
+    case 'median':
+      return median(values)
+    case 'min':
+      return min(values)
+    case 'max':
+      return max(values)
+    case 'count':
+      return count(values)
+    case 'none':
+      return none(values)
+    default:
+      throw new Error(`Unknown aggregate type: ${type}`)
+  }
+}

package/src/utils/colorUtils.ts

@@ -0,0 +1,63 @@
+import type { Theme } from '../types'
+
+/**
+ * 根據索引和主題計算對應的顏色
+ * @param index 索引值
+ * @param theme 主題設定
+ * @returns 對應的顏色（hex 格式）
+ */
+export function getColorByIndex(index: number, theme: Theme): string {
+  // 根據 colorScheme 決定使用哪個色彩方案
+  let colorScheme: 'light' | 'dark'
+  if (theme.colorScheme === 'auto') {
+    // 可以根據系統設定或其他邏輯來決定，這裡預設使用 light
+    colorScheme = 'light'
+  } else {
+    colorScheme = theme.colorScheme
+  }
+
+  const dataColors = theme.colors[colorScheme].data
+  
+  // 使用模運算來循環使用色票
+  const colorIndex = index % dataColors.length
+  return dataColors[colorIndex]
+}
+
+/**
+ * 根據不同的 encoding.color.from 計算顏色
+ * @param colorFrom 顏色來源類型
+ * @param options 包含所有可能索引的選項物件
+ * @param theme 主題設定
+ * @returns 對應的顏色（hex 格式）
+ */
+export function getColorByFrom(
+  colorFrom: 'index' | 'series' | 'category' | 'dataset',
+  options: {
+    index?: number
+    seriesIndex?: number
+    categoryIndex?: number
+    datasetIndex?: number
+  },
+  theme: Theme
+): string {
+  let targetIndex: number
+  
+  switch (colorFrom) {
+    case 'index':
+      targetIndex = options.index ?? 0
+      break
+    case 'series':
+      targetIndex = options.seriesIndex ?? 0
+      break
+    case 'category':
+      targetIndex = options.categoryIndex ?? 0
+      break
+    case 'dataset':
+      targetIndex = options.datasetIndex ?? 0
+      break
+    default:
+      targetIndex = 0
+  }
+  
+  return getColorByIndex(targetIndex, theme)
+}

package/src/utils/commonUtils.ts

@@ -1,3 +1,4 @@
+import { DeepPartial } from "../types/Common";
 
 // 是否為原始物件
 export function isPlainObject(variable: any) {
@@ -16,31 +17,31 @@ export function isDom(obj: any) {
 }
 
 // 將可選的參數和預設值合併
-export function mergeOptionsWithDefault<Options extends { [key: string]: any; }> (options: {[key: string]: any}, defaultOptions: Options): Options {
-  if (isPlainObject(options) === false || isPlainObject(defaultOptions) === false) {
-    return Object.assign({}, defaultOptions)
+export function deepOverwrite<DeepRecord extends Record<string, any>>(full: DeepRecord, options: DeepPartial<DeepRecord>): DeepRecord {
+  if (isPlainObject(options) === false || isPlainObject(full) === false) {
+    return Object.assign({}, full)
   }
-  const mergeObjColumns = (_options: {[key: string]: any}, _defaultOptions: {[key: string]: any}) => {
-    const obj: Options = (Object.assign({}, _defaultOptions) as any)
+  const mergeObject = (_full: DeepRecord, _options: DeepPartial<DeepRecord>) => {
+    const obj: DeepRecord = (Object.assign({}, _full) as any)
     for (let key of Object.keys(_options)) {
-      if ((key in _defaultOptions) == false) {
+      if ((key in _full) == false) {
         continue
       }
       let objValue: any = undefined
       // 下一層的plain object
-      if (isPlainObject(_options[key]) && isPlainObject(_defaultOptions[key])) {
-        objValue = mergeObjColumns(_options[key], _defaultOptions[key])
-        obj[key as keyof Options] = objValue
+      if (isPlainObject(_options[key]) && isPlainObject(_full[key])) {
+        objValue = mergeObject(_full[key], _options[key])
+        obj[key as keyof DeepRecord] = objValue
       }
       // 不是plain object直接賦值
       else {
-        obj[key as keyof Options] = _options[key]
+        obj[key as keyof DeepRecord] = _options[key] as DeepRecord[typeof key]
       }
     }
     return obj
   }
   
-  return mergeObjColumns(options, defaultOptions)
+  return mergeObject(full, options)
 }
 
 // 加上千分位 ,

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)
+    }
+  }
+}