@orbcharts/core 3.0.6 → 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,55 +1,56 @@
-
-// 是否為原始物件
-export function isPlainObject(variable: any) {
-  return Object.prototype.toString.call(variable) === "[object Object]";
-}
-
-// 是否為function
-export function isFunction(fn: any) {
-  // return !!fn && !fn.nodename && fn.constructor != String && fn.constructor != RegExp && fn.constructor != Array && /function/i.test(fn + "");
-  return Object.prototype.toString.call(fn) === '[object Function]'
-}
-
-// 是否為dom
-export function isDom(obj: any) {
-  return !!(obj && obj.nodeType);
-}
-
-// 將可選的參數和預設值合併
-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)
-  }
-  const mergeObjColumns = (_options: {[key: string]: any}, _defaultOptions: {[key: string]: any}) => {
-    const obj: Options = (Object.assign({}, _defaultOptions) as any)
-    for (let key of Object.keys(_options)) {
-      if ((key in _defaultOptions) == 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
-      }
-      // 不是plain object直接賦值
-      else {
-        obj[key as keyof Options] = _options[key]
-      }
-    }
-    return obj
-  }
-  
-  return mergeObjColumns(options, defaultOptions)
-}
-
-// 加上千分位 ,
-export function formatCommaNumber (num = 0): string {
-  try {
-    let parts = num.toString().split('.');
-    parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ',');
-    return parts.join('.');
-  } catch (e: any) {
-    console.error(e)
-  }
-}
+import { DeepPartial } from "../types/Common";
+
+// 是否為原始物件
+export function isPlainObject(variable: any) {
+  return Object.prototype.toString.call(variable) === "[object Object]";
+}
+
+// 是否為function
+export function isFunction(fn: any) {
+  // return !!fn && !fn.nodename && fn.constructor != String && fn.constructor != RegExp && fn.constructor != Array && /function/i.test(fn + "");
+  return Object.prototype.toString.call(fn) === '[object Function]'
+}
+
+// 是否為dom
+export function isDom(obj: any) {
+  return !!(obj && obj.nodeType);
+}
+
+// 將可選的參數和預設值合併
+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 mergeObject = (_full: DeepRecord, _options: DeepPartial<DeepRecord>) => {
+    const obj: DeepRecord = (Object.assign({}, _full) as any)
+    for (let key of Object.keys(_options)) {
+      if ((key in _full) == false) {
+        continue
+      }
+      let objValue: any = undefined
+      // 下一層的plain object
+      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 DeepRecord] = _options[key] as DeepRecord[typeof key]
+      }
+    }
+    return obj
+  }
+  
+  return mergeObject(full, options)
+}
+
+// 加上千分位 ,
+export function formatCommaNumber (num = 0): string {
+  try {
+    let parts = num.toString().split('.');
+    parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+    return parts.join('.');
+  } catch (e: any) {
+    console.error(e)
+  }
+}