@vela-studio/ui 1.0.1

package/src/hooks/useDataSource.ts

@@ -0,0 +1,123 @@
+import { ref, watch, onUnmounted, type Ref } from 'vue'
+import axios, { type AxiosRequestConfig } from 'axios'
+
+export interface DataSource {
+  enabled?: boolean
+  url?: string
+  method?: string
+  headers?: Record<string, string>
+  body?: string
+  interval?: number
+}
+
+/**
+ * 数据源 Hook
+ * 支持 HTTP 请求和自动刷新
+ *
+ * 职责：仅负责网络请求，返回完整响应数据
+ * 数据提取：由各组件使用 dataUtils 工具函数自行提取所需字段
+ * 优势：组件可灵活提取多个字段，互不影响
+ */
+export function useDataSource(dataSource: Ref<DataSource | undefined>) {
+  const data = ref<unknown>(null)
+  const rawData = ref<unknown>(null) // 完整响应数据
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+  let intervalId: number | null = null
+
+  /**
+   * 执行数据请求
+   */
+  const fetchData = async () => {
+    const ds = dataSource.value
+    if (!ds || !ds.enabled || !ds.url) {
+      return
+    }
+
+    loading.value = true
+    error.value = null
+
+    try {
+      // 构建请求配置
+      const config: AxiosRequestConfig = {
+        method: ds.method || 'GET',
+        url: ds.url,
+        headers: ds.headers || {},
+      }
+
+      // 处理请求体（仅 POST/PUT/DELETE）
+      if (ds.method && ['POST', 'PUT', 'DELETE'].includes(ds.method) && ds.body) {
+        try {
+          config.data = JSON.parse(ds.body)
+        } catch {
+          error.value = '请求体 JSON 格式错误'
+          loading.value = false
+          return
+        }
+      }
+
+      // 发送请求
+      const response = await axios(config)
+
+      // 保存完整响应数据
+      rawData.value = response.data
+      data.value = response.data
+      error.value = null
+    } catch (err: unknown) {
+      error.value = (err as Error).message || '请求失败'
+      console.error('Data source fetch error:', err)
+    } finally {
+      loading.value = false
+    }
+  }
+
+  /**
+   * 启动定时刷新
+   */
+  const startPolling = () => {
+    stopPolling()
+    const ds = dataSource.value
+    if (ds && ds.enabled && ds.interval && ds.interval > 0) {
+      // interval 单位为秒，转换为毫秒
+      intervalId = window.setInterval(fetchData, ds.interval * 1000)
+    }
+  }
+
+  /**
+   * 停止定时刷新
+   */
+  const stopPolling = () => {
+    if (intervalId !== null) {
+      clearInterval(intervalId)
+      intervalId = null
+    }
+  }
+
+  // 监听 dataSource 变化
+  watch(
+    () => dataSource.value,
+    (newDs) => {
+      stopPolling()
+      if (newDs && newDs.enabled && newDs.url) {
+        fetchData()
+        startPolling()
+      } else {
+        data.value = null
+      }
+    },
+    { immediate: true, deep: true },
+  )
+
+  // 组件卸载时清理定时器
+  onUnmounted(() => {
+    stopPolling()
+  })
+
+  return {
+    data,
+    rawData, // 完整响应数据
+    loading,
+    error,
+    fetchData, // 手动刷新
+  }
+}

package/src/types/gis.ts

@@ -0,0 +1,251 @@
+/**
+ * GIS 通用类型定义
+ * Smart 和 Dumb 组件之间的数据契约
+ */
+
+// ==================== 基础类型 ====================
+
+/** 基础坐标点 */
+export interface GISPoint {
+  lat: number
+  lng: number
+}
+
+/** 带强度的热力点 */
+export interface HeatPoint extends GISPoint {
+  /** 热力强度 0-1 */
+  intensity?: number
+}
+
+/** 聚合/标记点数据 */
+export interface MarkerPoint extends GISPoint {
+  /** 唯一标识 */
+  id?: string | number
+  /** 标签文本 */
+  label?: string
+  /** 弹窗内容 */
+  popup?: string
+  /** 图标 URL */
+  icon?: string
+  /** 图标大小 [width, height] */
+  iconSize?: [number, number]
+  /** 图标锚点 [x, y] */
+  iconAnchor?: [number, number]
+  /** 自定义数据 */
+  data?: Record<string, unknown>
+}
+
+// ==================== GeoJSON 类型 ====================
+
+/** GeoJSON 几何类型 */
+export type GeoJSONGeometryType =
+  | 'Point'
+  | 'MultiPoint'
+  | 'LineString'
+  | 'MultiLineString'
+  | 'Polygon'
+  | 'MultiPolygon'
+  | 'GeometryCollection'
+
+/** GeoJSON 几何对象 */
+export interface GeoJSONGeometry {
+  type: GeoJSONGeometryType
+  coordinates: number[] | number[][] | number[][][] | number[][][][]
+}
+
+/** GeoJSON Feature */
+export interface GeoJSONFeature<P = Record<string, unknown>> {
+  type: 'Feature'
+  geometry: GeoJSONGeometry
+  properties: P
+  id?: string | number
+}
+
+/** GeoJSON FeatureCollection */
+export interface GeoJSONFeatureCollection<P = Record<string, unknown>> {
+  type: 'FeatureCollection'
+  features: GeoJSONFeature<P>[]
+}
+
+/** GeoJSON 数据类型联合 */
+export type GeoJSONData<P = Record<string, unknown>> =
+  | GeoJSONFeature<P>
+  | GeoJSONFeatureCollection<P>
+
+// ==================== 地图配置类型 ====================
+
+/** 边界框 */
+export interface MapBounds {
+  northEast: GISPoint
+  southWest: GISPoint
+}
+
+/** 地图视口配置 */
+export interface MapViewport {
+  center: GISPoint
+  zoom: number
+  bounds?: MapBounds
+}
+
+/** 瓦片图层配置 */
+export interface TileLayerConfig {
+  url: string
+  attribution?: string
+  minZoom?: number
+  maxZoom?: number
+  subdomains?: string[]
+  opacity?: number
+}
+
+/** 图层可见性配置 */
+export interface LayerVisibility {
+  id: string
+  name: string
+  visible: boolean
+  type: 'tile' | 'heat' | 'cluster' | 'geojson' | 'vector'
+}
+
+// ==================== 热力图配置类型 ====================
+
+/** 热力图渐变色配置 */
+export interface HeatGradient {
+  [stop: number]: string
+}
+
+/** 热力图配置 */
+export interface HeatLayerConfig {
+  /** 热力点半径（像素） */
+  radius?: number
+  /** 模糊程度（像素） */
+  blur?: number
+  /** 最大缩放级别 */
+  maxZoom?: number
+  /** 最大强度值 */
+  max?: number
+  /** 最小透明度 */
+  minOpacity?: number
+  /** 渐变色配置 */
+  gradient?: HeatGradient
+}
+
+// ==================== 聚合图配置类型 ====================
+
+/** 聚合图标配置 */
+export interface ClusterIconConfig {
+  /** 默认图标 URL */
+  iconUrl?: string
+  /** 图标大小 */
+  iconSize?: [number, number]
+  /** 图标锚点 */
+  iconAnchor?: [number, number]
+  /** 弹窗锚点 */
+  popupAnchor?: [number, number]
+}
+
+/** 聚合簇样式配置 */
+export interface ClusterStyleConfig {
+  /** 小聚合簇阈值 */
+  smallThreshold?: number
+  /** 中聚合簇阈值 */
+  mediumThreshold?: number
+  /** 小聚合簇样式 */
+  smallStyle?: {
+    backgroundColor?: string
+    color?: string
+    size?: number
+  }
+  /** 中聚合簇样式 */
+  mediumStyle?: {
+    backgroundColor?: string
+    color?: string
+    size?: number
+  }
+  /** 大聚合簇样式 */
+  largeStyle?: {
+    backgroundColor?: string
+    color?: string
+    size?: number
+  }
+}
+
+/** 聚合图层配置 */
+export interface ClusterLayerConfig {
+  /** 最大聚合半径 */
+  maxClusterRadius?: number
+  /** 禁用聚合的缩放级别 */
+  disableClusteringAtZoom?: number
+  /** 最大缩放时展开为蜘蛛网形式 */
+  spiderfyOnMaxZoom?: boolean
+  /** 鼠标悬停时显示聚合范围 */
+  showCoverageOnHover?: boolean
+  /** 点击聚合簇时缩放到边界 */
+  zoomToBoundsOnClick?: boolean
+  /** 是否启用分块加载 */
+  chunkedLoading?: boolean
+  /** 图标配置 */
+  iconConfig?: ClusterIconConfig
+  /** 聚合簇样式 */
+  clusterStyle?: ClusterStyleConfig
+}
+
+// ==================== 事件类型 ====================
+
+/** 地图点击事件数据 */
+export interface MapClickEvent {
+  latlng: GISPoint
+  layerPoint: { x: number; y: number }
+  containerPoint: { x: number; y: number }
+}
+
+/** 标记点击事件数据 */
+export interface MarkerClickEvent {
+  marker: MarkerPoint
+  index: number
+  originalEvent?: MouseEvent
+}
+
+/** 聚合簇点击事件数据 */
+export interface ClusterClickEvent {
+  /** 聚合簇中心点 */
+  center: GISPoint
+  /** 聚合簇包含的标记数量 */
+  count: number
+  /** 聚合簇边界 */
+  bounds: MapBounds
+  /** 聚合簇内的所有标记 */
+  markers: MarkerPoint[]
+}
+
+// ==================== 数据状态类型 ====================
+
+/** 数据加载状态 */
+export type DataLoadingState = 'idle' | 'loading' | 'success' | 'error'
+
+/** 带状态的数据包装器 */
+export interface DataWithState<T> {
+  data: T
+  state: DataLoadingState
+  error?: string
+  /** 数据版本号，用于增量更新检测 */
+  version?: number
+}
+
+// ==================== 工具类型 ====================
+
+/** 将普通数组转换为 HeatPoint 数组的映射配置 */
+export interface HeatDataMapping {
+  latField: string
+  lngField: string
+  intensityField?: string
+}
+
+/** 将普通数组转换为 MarkerPoint 数组的映射配置 */
+export interface MarkerDataMapping {
+  idField?: string
+  latField: string
+  lngField: string
+  labelField?: string
+  popupField?: string
+  iconField?: string
+  dataFields?: string[]
+}

package/src/utils/chartUtils.ts

@@ -0,0 +1,349 @@
+/**
+ * 数据提取工具函数（通用）
+ * 用于所有组件的数据源、路径解析、数据格式化等
+ * 图表、KPI、Text 等组件都使用这些工具函数提取数据
+ */
+
+/**
+ * 从对象中根据路径提取值
+ * 支持点号路径和数组索引，如: "data.chart.values" 或 "items[0].name"
+ *
+ * @param obj - 源数据对象
+ * @param path - 提取路径，可选（为空则返回 undefined）
+ * @returns 提取的值，或 undefined
+ */
+export function getValueByPath(obj: unknown, path: string | undefined): unknown {
+  if (!path || !obj) return undefined
+  try {
+    const keys = path.replace(/\[(\d+)\]/g, '.$1').split('.')
+    let result: unknown = obj
+    for (const key of keys) {
+      if (result === null || result === undefined) return undefined
+      result = (result as Record<string, unknown>)[key]
+    }
+    return result
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 从数据源提取单个数值
+ * 用于 KPI 组件（countUp, progress, badge 等）
+ *
+ * @param remoteData - 远程数据对象
+ * @param valuePath - 数值路径，可选
+ * @param defaultValue - 默认值
+ * @returns 提取的数值
+ */
+export function extractNumber(
+  remoteData: unknown,
+  valuePath: string | undefined,
+  defaultValue: number = 0,
+): number {
+  if (!valuePath) return defaultValue
+
+  const value = getValueByPath(remoteData, valuePath)
+  if (typeof value === 'number') return value
+  if (value !== undefined && value !== null) {
+    const parsed = parseFloat(String(value))
+    return isNaN(parsed) ? defaultValue : parsed
+  }
+
+  return defaultValue
+}
+
+/**
+ * 解析逗号分隔的数字输入
+ * 支持 JSON 数组格式和逗号分隔格式
+ * @param input - 输入字符串，如 "150, 230, 224" 或 "[150, 230, 224]"
+ * @param defaultValue - 默认值数组
+ */
+export function parseNumberInput(input: string | undefined, defaultValue: number[] = []): number[] {
+  if (!input) return defaultValue
+
+  // 尝试 JSON 解析
+  try {
+    const parsed = JSON.parse(input)
+    if (Array.isArray(parsed)) {
+      return parsed
+        .map((v) => (typeof v === 'number' ? v : parseFloat(String(v))))
+        .filter((v) => !isNaN(v))
+    }
+  } catch {
+    // JSON 解析失败，尝试逗号分隔
+  }
+
+  // 逗号分隔解析
+  return input
+    .split(',')
+    .map((v) => parseFloat(v.trim()))
+    .filter((v) => !isNaN(v))
+}
+
+/**
+ * 解析逗号分隔的字符串输入
+ * 支持 JSON 数组格式和逗号分隔格式
+ * @param input - 输入字符串，如 "Mon, Tue, Wed" 或 '["Mon", "Tue", "Wed"]'
+ * @param defaultValue - 默认值数组
+ */
+export function parseStringInput(input: string | undefined, defaultValue: string[] = []): string[] {
+  if (!input) return defaultValue
+
+  // 尝试 JSON 解析
+  try {
+    const parsed = JSON.parse(input)
+    if (Array.isArray(parsed)) {
+      return parsed.map((v) => String(v))
+    }
+  } catch {
+    // JSON 解析失败，尝试逗号分隔
+  }
+
+  // 逗号分隔解析
+  return input
+    .split(',')
+    .map((v) => v.trim())
+    .filter((v) => v.length > 0)
+}
+
+/**
+ * 解析二维数组输入（用于散点图等）
+ * @param input - 输入字符串，如 "[[10, 8], [8, 7]]"
+ * @param defaultValue - 默认值数组
+ */
+export function parse2DArrayInput(
+  input: string | undefined,
+  defaultValue: Array<[number, number]> = [],
+): Array<[number, number]> {
+  if (!input) return defaultValue
+
+  try {
+    const parsed = JSON.parse(input)
+    if (Array.isArray(parsed) && parsed.length > 0 && Array.isArray(parsed[0])) {
+      return parsed.map((item) => {
+        if (Array.isArray(item) && item.length >= 2) {
+          return [
+            typeof item[0] === 'number' ? item[0] : parseFloat(String(item[0])),
+            typeof item[1] === 'number' ? item[1] : parseFloat(String(item[1])),
+          ] as [number, number]
+        }
+        return [0, 0] as [number, number]
+      })
+    }
+  } catch {
+    // JSON 解析失败
+  }
+
+  return defaultValue
+}
+
+/**
+ * 从数据源提取数字数组
+ * @param remoteData - 远程数据对象
+ * @param dataPath - 数据路径
+ */
+export function extractNumberArray(
+  remoteData: unknown,
+  dataPath: string | undefined,
+): number[] | undefined {
+  if (!dataPath) return undefined
+
+  const extractedData = getValueByPath(remoteData, dataPath)
+  if (Array.isArray(extractedData)) {
+    return extractedData.map((v) => (typeof v === 'number' ? v : parseFloat(String(v))))
+  }
+
+  return undefined
+}
+
+/**
+ * 从数据源提取字符串数组
+ * @param remoteData - 远程数据对象
+ * @param dataPath - 数据路径
+ */
+export function extractStringArray(
+  remoteData: unknown,
+  dataPath: string | undefined,
+): string[] | undefined {
+  if (!dataPath) return undefined
+
+  const extractedData = getValueByPath(remoteData, dataPath)
+  if (Array.isArray(extractedData)) {
+    return extractedData.map((v) => String(v))
+  }
+
+  return undefined
+}
+
+/**
+ * 从数据源提取二维数组（用于散点图等）
+ * @param remoteData - 远程数据对象
+ * @param dataPath - 数据路径
+ */
+export function extract2DArray(
+  remoteData: unknown,
+  dataPath: string | undefined,
+): Array<[number, number]> | undefined {
+  if (!dataPath) return undefined
+
+  const extractedData = getValueByPath(remoteData, dataPath)
+  if (Array.isArray(extractedData) && extractedData.length > 0 && Array.isArray(extractedData[0])) {
+    return extractedData.map((item) => {
+      if (Array.isArray(item) && item.length >= 2) {
+        return [
+          typeof item[0] === 'number' ? item[0] : parseFloat(String(item[0])),
+          typeof item[1] === 'number' ? item[1] : parseFloat(String(item[1])),
+        ] as [number, number]
+      }
+      return [0, 0] as [number, number]
+    })
+  }
+
+  return undefined
+}
+
+/**
+ * 从数据源提取字符串值
+ * @param remoteData - 远程数据对象
+ * @param dataPath - 数据路径
+ */
+export function extractString(
+  remoteData: unknown,
+  dataPath: string | undefined,
+): string | undefined {
+  if (!dataPath) return undefined
+
+  const extractedData = getValueByPath(remoteData, dataPath)
+  return extractedData ? String(extractedData) : undefined
+}
+
+/**
+ * 解析 JSON 数组输入（通用）
+ * @param input - JSON 字符串输入
+ * @param defaultValue - 默认值
+ */
+export function parseJSONInput<T = unknown>(input: string | undefined, defaultValue: T): T {
+  if (!input) return defaultValue
+
+  try {
+    const parsed = JSON.parse(input)
+    return parsed as T
+  } catch (e) {
+    console.error('Failed to parse JSON input:', e)
+    return defaultValue
+  }
+}
+
+/**
+ * 提取并规范化 Sankey 图节点数据
+ * @param remoteData - 远程数据对象
+ * @param dataPath - 数据路径
+ */
+export function extractSankeyNodes(
+  remoteData: unknown,
+  dataPath: string | undefined,
+): Array<{ name: string; value?: number; depth?: number; itemStyle?: unknown }> | undefined {
+  if (!dataPath) return undefined
+
+  const nodesData = getValueByPath(remoteData, dataPath)
+  if (!Array.isArray(nodesData) || nodesData.length === 0) return undefined
+
+  return nodesData.map((node: unknown) => {
+    const obj =
+      typeof node === 'object' && node !== null ? (node as Record<string, unknown>) : undefined
+    const name = typeof node === 'string' ? node : String(obj?.name ?? obj?.id ?? '')
+
+    return {
+      name,
+      value:
+        obj && typeof obj.value === 'number'
+          ? (obj.value as number)
+          : obj && obj.value != null
+            ? parseFloat(String(obj.value))
+            : undefined,
+      depth:
+        obj && typeof obj.depth === 'number'
+          ? (obj.depth as number)
+          : obj && obj.depth != null
+            ? parseFloat(String(obj.depth))
+            : undefined,
+      itemStyle: obj ? obj.itemStyle : undefined,
+    }
+  })
+}
+
+/**
+ * 提取并规范化 Sankey 图连接数据
+ * @param remoteData - 远程数据对象
+ * @param dataPath - 数据路径
+ */
+export function extractSankeyLinks(
+  remoteData: unknown,
+  dataPath: string | undefined,
+): Array<{ source: string; target: string; value: number }> | undefined {
+  if (!dataPath) return undefined
+
+  const linksData = getValueByPath(remoteData, dataPath)
+  if (!Array.isArray(linksData) || linksData.length === 0) return undefined
+
+  return linksData.map((link: unknown) => {
+    const l = link as Record<string, unknown>
+    return {
+      source: (l.source || l.from || '') as string,
+      target: (l.target || l.to || '') as string,
+      value: (l.value || 0) as number,
+    }
+  })
+}
+
+/**
+ * KPI 组件专用：提取多个字段的数据
+ * 用于 stat 组件等需要同时提取多个字段的场景
+ *
+ * @param remoteData - 远程数据对象
+ * @param paths - 字段路径映射 { title: 'data.title', value: 'data.value', ... }
+ * @returns 提取的数据对象
+ *
+ * @example
+ * const data = extractMultipleFields(remoteData, {
+ *   title: 'data.kpi.title',
+ *   value: 'data.kpi.value',
+ *   change: 'data.kpi.change'
+ * })
+ * // 返回: { title: '销售额', value: 12345, change: 5.2 }
+ */
+export function extractMultipleFields<T extends Record<string, string | undefined>>(
+  remoteData: unknown,
+  paths: T,
+): Record<keyof T, unknown> {
+  const result: Record<string, unknown> = {}
+
+  for (const [key, path] of Object.entries(paths)) {
+    if (path && typeof path === 'string') {
+      result[key] = getValueByPath(remoteData, path)
+    }
+  }
+
+  return result as Record<keyof T, unknown>
+}
+
+/**
+ * 智能提取数据：优先使用路径提取，否则使用默认值
+ * 用于所有简单组件（text, countUp, progress, badge 等）
+ *
+ * @param remoteData - 远程数据对象
+ * @param path - 数据路径
+ * @param fallbackValue - 回退值（当路径未配置或提取失败时使用）
+ * @returns 提取的数据或回退值
+ */
+export function extractWithFallback<T>(
+  remoteData: unknown,
+  path: string | undefined,
+  fallbackValue: T,
+): T {
+  if (!path) return fallbackValue
+
+  const extracted = getValueByPath(remoteData, path)
+  return (extracted ?? fallbackValue) as T
+}