@fses/workbench-app 0.2.0 → 0.2.1

package/node_modules/@fses/workbench-card/src/renderers/chart/echarts-protocol/converters/table.converter.ts

@@ -0,0 +1,195 @@
+/**
+ * @fileoverview Table protocol converter - maps tabular protocol data to ECharts dataset options.
+ * @author seadon
+ * @created 2026-05-05
+ */
+
+import type { EChartsOption } from 'echarts';
+
+import type {
+  ProtocolConfigPayload,
+  ProtocolConverter,
+  ProtocolDataPayload,
+  TableDataPayload,
+} from '../types';
+
+type PlainRecord = Record<string, unknown>;
+
+/**
+ * Checks whether a value is a spreadable object.
+ * @param value - Candidate value from protocol data or ECharts option.
+ * @returns True when the value is a non-array object.
+ */
+function isPlainRecord(value: unknown): value is PlainRecord {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+/**
+ * Reads the first table dataset from a protocol payload.
+ * @param data - Protocol data payload.
+ * @returns First table dataset, when present.
+ */
+function firstTableDataset(data: ProtocolDataPayload): TableDataPayload['datasets'][number] | undefined {
+  return (data as TableDataPayload).datasets[0];
+}
+
+/**
+ * Reads table rows in the order preferred by the table protocol.
+ * @param dataset - Table dataset.
+ * @returns Record rows or array source rows.
+ */
+function tableDatasetSource(dataset: TableDataPayload['datasets'][number]): unknown[] {
+  return dataset.rows?.length ? dataset.rows : dataset.source;
+}
+
+/**
+ * Normalizes an option series field to an array of records.
+ * @param value - ECharts option series field.
+ * @returns Series records.
+ */
+function optionSeriesRecords(value: unknown): PlainRecord[] {
+  if (!value) return [];
+  return (Array.isArray(value) ? value : [value]).filter(isPlainRecord);
+}
+
+/**
+ * Resolves the dataset id that table series should use.
+ * @param option - Current ECharts option.
+ * @param fallback - Protocol dataset id fallback.
+ * @returns Stable dataset id.
+ */
+function resolveDatasetId(option: EChartsOption, fallback: string | undefined): string {
+  const referencedId = optionSeriesRecords((option as PlainRecord).series)
+    .map((series) => series.datasetId)
+    .find((value): value is string => typeof value === 'string' && value.trim().length > 0);
+  return referencedId || fallback || 'main';
+}
+
+/**
+ * Removes empty inline data from series that should draw through dataset.
+ * @param series - ECharts series item.
+ * @param datasetId - Hydrated dataset id.
+ * @returns Normalized series item.
+ */
+function normalizeTableSeries(series: PlainRecord, datasetId: string): PlainRecord {
+  const next: PlainRecord = { ...series };
+  if (!next.datasetId && next.datasetIndex === undefined) {
+    next.datasetId = datasetId;
+  }
+  if (Array.isArray(next.data) && next.data.length === 0 && (next.datasetId || next.datasetIndex !== undefined)) {
+    delete next.data;
+  }
+  return next;
+}
+
+/**
+ * Normalizes every series item for dataset-driven table rendering.
+ * @param value - ECharts option series field.
+ * @param datasetId - Hydrated dataset id.
+ * @returns Normalized series field.
+ */
+function normalizeSeriesField(value: unknown, datasetId: string): unknown {
+  if (!value) return value;
+  if (Array.isArray(value)) {
+    return value.map((item) => (isPlainRecord(item) ? normalizeTableSeries(item, datasetId) : item));
+  }
+  return isPlainRecord(value) ? normalizeTableSeries(value, datasetId) : value;
+}
+
+/**
+ * Hydrates an object-form dataset with table data.
+ * @param dataset - Existing dataset option.
+ * @param datasetId - Dataset id referenced by series.
+ * @param source - Table source rows.
+ * @param dimensions - Optional table dimensions.
+ * @returns Hydrated dataset option.
+ */
+function hydrateObjectDataset(
+  dataset: unknown,
+  datasetId: string,
+  source: unknown[],
+  dimensions: unknown[] | undefined,
+): PlainRecord {
+  return {
+    ...(isPlainRecord(dataset) ? dataset : {}),
+    id: datasetId,
+    source: source as any,
+    ...(dimensions?.length ? { dimensions } : {}),
+  };
+}
+
+/**
+ * Hydrates the first dataset in an array-form dataset option.
+ * @param datasets - Existing dataset option array.
+ * @param datasetId - Dataset id referenced by series.
+ * @param source - Table source rows.
+ * @param dimensions - Optional table dimensions.
+ * @returns Hydrated dataset option array.
+ */
+function hydrateDatasetArray(
+  datasets: unknown[],
+  datasetId: string,
+  source: unknown[],
+  dimensions: unknown[] | undefined,
+): unknown[] {
+  if (datasets.length === 0) return [hydrateObjectDataset({}, datasetId, source, dimensions)];
+  return datasets.map((dataset, index) => (
+    index === 0 ? hydrateObjectDataset(dataset, datasetId, source, dimensions) : dataset
+  ));
+}
+
+/**
+ * Table protocol converter for ECharts dataset-driven charts.
+ */
+export const tableConverter: ProtocolConverter = {
+  /**
+   * Builds the empty dataset option skeleton from table config.
+   * @param config - Protocol config payload.
+   * @returns ECharts option skeleton.
+   */
+  buildOption(config: ProtocolConfigPayload): EChartsOption {
+    const datasetId = config.series.find((def) => def.datasetId)?.datasetId || 'main';
+    const option: EChartsOption = {
+      dataset: {
+        id: datasetId,
+        source: [],
+      },
+      series: config.series.map((def) => ({
+        id: def.id,
+        type: def.type,
+        datasetId: def.datasetId || datasetId,
+      })) as any[],
+    };
+
+    if (config.optionPatch) {
+      Object.assign(option, config.optionPatch);
+    }
+
+    return option;
+  },
+
+  /**
+   * Merges table protocol data into the existing ECharts option.
+   * @param option - Current ECharts option.
+   * @param data - Protocol data payload.
+   * @returns Updated ECharts option.
+   */
+  mergeData(option: EChartsOption, data: ProtocolDataPayload): EChartsOption {
+    const merged = { ...option };
+    const firstDataset = firstTableDataset(data);
+    if (!firstDataset) return merged;
+
+    const source = tableDatasetSource(firstDataset);
+    const dimensions = Array.isArray(firstDataset.dimensions)
+      ? firstDataset.dimensions as unknown[]
+      : undefined;
+    const datasetId = resolveDatasetId(merged, firstDataset.id);
+
+    merged.dataset = (Array.isArray(merged.dataset)
+      ? hydrateDatasetArray(merged.dataset as unknown[], datasetId, source, dimensions)
+      : hydrateObjectDataset(merged.dataset, datasetId, source, dimensions)) as EChartsOption['dataset'];
+    merged.series = normalizeSeriesField(merged.series, datasetId) as any;
+
+    return merged;
+  },
+};

package/node_modules/@fses/workbench-card/src/renderers/chart/echarts-protocol/converters/timeline.converter.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Timeline 协议转换器 — 将时间轴数据转换为 ECharts option
+ * @author seadon
+ * @created 2026-05-05
+ */
+
+import type { EChartsOption } from 'echarts';
+
+import type {
+  ProtocolConfigPayload,
+  ProtocolConverter,
+  ProtocolDataPayload,
+  TimelineDataPayload,
+} from '../types';
+
+/**
+ * Timeline 协议转换器，处理带有时间轴切换功能的图表数据
+ * 使用 ECharts timeline 组件实现多状态切换
+ */
+export const timelineConverter: ProtocolConverter = {
+  /**
+   * 根据协议配置构建包含时间轴的 ECharts option 骨架
+   * @param config - 协议配置载荷
+   * @returns 包含 timeline 组件和基础配置的 ECharts option
+   */
+  buildOption(config: ProtocolConfigPayload): EChartsOption {
+    const option: EChartsOption = {
+      baseOption: {
+        timeline: {
+          axisType: 'category',
+        },
+      },
+      options: [],
+    };
+
+    if (config.optionPatch) {
+      Object.assign(option, config.optionPatch);
+    }
+
+    return option;
+  },
+
+  /**
+   * 将时间轴数据合并到已有的 ECharts option 中
+   * dataset 中除 id/shape 外的属性会展开为 option 属性
+   * @param option - 已有的 ECharts option
+   * @param data - 协议数据载荷，包含时间轴相关数据
+   * @returns 更新后的 ECharts option
+   */
+  mergeData(option: EChartsOption, data: ProtocolDataPayload): EChartsOption {
+    const timelineData = data as TimelineDataPayload;
+    const merged = { ...option };
+    const dataset = timelineData.dataset;
+    if (!dataset) return merged;
+
+    // 将 dataset 中除 id/shape 外的属性展开到 option 中
+    const { id: _id, shape: _shape, ...rest } = dataset;
+    Object.assign(merged, rest);
+
+    return merged;
+  },
+};

package/node_modules/@fses/workbench-card/src/renderers/chart/echarts-protocol/converters/transition.converter.ts

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Transition 协议转换器 — 将动画过渡数据转换为 ECharts option
+ * @author seadon
+ * @created 2026-05-05
+ */
+
+import type { EChartsOption } from 'echarts';
+
+import type {
+  ProtocolConfigPayload,
+  ProtocolConverter,
+  ProtocolDataPayload,
+  TransitionDataPayload,
+} from '../types';
+
+/**
+ * Transition 协议转换器，处理动画状态过渡数据
+ * 依赖 optionPatch 定义完整的系列结构
+ */
+export const transitionConverter: ProtocolConverter = {
+  /**
+   * 根据协议配置构建动画过渡图表的 ECharts option 骨架
+   * 仅创建空系列数组，系列结构由 optionPatch 定义
+   * @param config - 协议配置载荷
+   * @returns 包含空系列数组的 ECharts option
+   */
+  buildOption(config: ProtocolConfigPayload): EChartsOption {
+    const option: EChartsOption = {
+      series: [],
+    };
+
+    if (config.optionPatch) {
+      Object.assign(option, config.optionPatch);
+    }
+
+    return option;
+  },
+
+  /**
+   * 将过渡数据合并到已有的 ECharts option 中
+   * dataset 中的属性会展开为顶层 option 属性
+   * @param option - 已有的 ECharts option
+   * @param data - 协议数据载荷
+   * @returns 更新后的 ECharts option
+   */
+  mergeData(option: EChartsOption, data: ProtocolDataPayload): EChartsOption {
+    const transitionData = data as TransitionDataPayload;
+    const merged = { ...option };
+    const dataset = transitionData.dataset;
+    if (!dataset) return merged;
+
+    // 将 dataset 中除 id/shape 外的属性展开到 option 中
+    const { id: _id, shape: _shape, ...rest } = dataset;
+    Object.assign(merged, rest);
+
+    return merged;
+  },
+};

package/node_modules/@fses/workbench-card/src/renderers/chart/echarts-protocol/converters/tree.converter.ts

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Tree 协议转换器 — 将层级树形数据转换为 ECharts option
+ * @author seadon
+ * @created 2026-05-05
+ */
+
+import type { EChartsOption } from 'echarts';
+
+import type {
+  ProtocolConfigPayload,
+  ProtocolConverter,
+  ProtocolDataPayload,
+  TreeDataPayload,
+} from '../types';
+
+/**
+ * Tree 协议转换器，处理层级嵌套的树形图表数据
+ */
+export const treeConverter: ProtocolConverter = {
+  /**
+   * 根据协议配置构建树形图表的 ECharts option 骨架
+   * 对 type='tree' 的系列添加布局定位参数
+   * @param config - 协议配置载荷
+   * @returns 包含空系列数据的 ECharts option
+   */
+  buildOption(config: ProtocolConfigPayload): EChartsOption {
+    // SeriesDef.type 为通用 string，需断言为 any 以满足 ECharts SeriesOption 字面量联合类型
+    const option: EChartsOption = {
+      series: config.series.map((def) => {
+        const seriesItem: Record<string, unknown> = {
+          id: def.id,
+          type: def.type,
+          data: [],
+        };
+
+        // 树形图表需要添加布局定位参数
+        if (def.type === 'tree') {
+          seriesItem.top = '5%';
+          seriesItem.left = '10%';
+          seriesItem.bottom = '5%';
+          seriesItem.right = '20%';
+        }
+
+        return seriesItem;
+      }) as any[],
+    };
+
+    if (config.optionPatch) {
+      Object.assign(option, config.optionPatch);
+    }
+
+    return option;
+  },
+
+  /**
+   * 将树形数据合并到已有的 ECharts option 中
+   * @param option - 已有的 ECharts option
+   * @param data - 协议数据载荷，包含树根节点
+   * @returns 更新后的 ECharts option
+   */
+  mergeData(option: EChartsOption, data: ProtocolDataPayload): EChartsOption {
+    const treeData = data as TreeDataPayload;
+    const merged = { ...option };
+
+    // 将根节点数据设置到每个系列中
+    if (Array.isArray(merged.series)) {
+      merged.series = merged.series.map((s) => ({
+        ...(s as Record<string, unknown>),
+        data: treeData.dataset.roots,
+      }));
+    }
+
+    return merged;
+  },
+};

package/node_modules/@fses/workbench-card/src/renderers/chart/echarts-protocol/converters/tuple.converter.ts

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Tuple 协议转换器 — 将元组结构数据转换为 ECharts option
+ * @author seadon
+ * @created 2026-05-05
+ */
+
+import type { EChartsOption } from 'echarts';
+
+import type {
+  ProtocolConfigPayload,
+  ProtocolConverter,
+  ProtocolDataPayload,
+  TupleDataPayload,
+} from '../types';
+
+/**
+ * 判断 tuple 数据是否应按整行数组传给单个系列。
+ * @param tupleKind - tuple 编码类型
+ * @param seriesType - ECharts 系列类型
+ * @returns 是否使用 dataset.rows 作为系列数据
+ */
+function shouldUseWholeRows(tupleKind: string, seriesType: unknown): boolean {
+  return tupleKind === 'candlestick'
+    || tupleKind === 'boxplot'
+    || tupleKind === 'heatmap'
+    || seriesType === 'candlestick'
+    || seriesType === 'boxplot'
+    || seriesType === 'heatmap';
+}
+
+/**
+ * Tuple 协议转换器，处理包含类别和元组行的数据结构
+ */
+export const tupleConverter: ProtocolConverter = {
+  /**
+   * 根据协议配置构建包含类别轴和数值轴的 ECharts option 骨架
+   * @param config - 协议配置载荷
+   * @returns 包含坐标轴和空系列的 ECharts option
+   */
+  buildOption(config: ProtocolConfigPayload): EChartsOption {
+    const option: EChartsOption = {
+      xAxis: {
+        type: 'category',
+      },
+      yAxis: {
+        type: 'value',
+      },
+      // SeriesDef.type 为通用 string，需断言为 any 以满足 ECharts SeriesOption 字面量联合类型
+      series: config.series.map((def) => ({
+        id: def.id,
+        type: def.type,
+        data: [],
+      })) as any[],
+    };
+
+    if (config.optionPatch) {
+      Object.assign(option, config.optionPatch);
+    }
+
+    return option;
+  },
+
+  /**
+   * 将元组数据合并到已有的 ECharts option 中
+   * @param option - 已有的 ECharts option
+   * @param data - 协议数据载荷，包含类别和数据行
+   * @returns 更新后的 ECharts option
+   */
+  mergeData(option: EChartsOption, data: ProtocolDataPayload): EChartsOption {
+    const tupleData = data as TupleDataPayload;
+    const merged = { ...option };
+    const dataset = tupleData.dataset;
+
+    // 设置 x 轴类别数据
+    if (dataset.categories?.xAxis) {
+      if (merged.xAxis && typeof merged.xAxis === 'object' && !Array.isArray(merged.xAxis)) {
+        merged.xAxis = { ...(merged.xAxis as Record<string, unknown>), data: dataset.categories.xAxis } as EChartsOption['xAxis'];
+      }
+    }
+
+    // 热力图的第二维是类别轴，需从 tuple dataset 的 yAxis categories 补齐。
+    const yAxisCategories = (dataset.categories as { yAxis?: string[] } | undefined)?.yAxis;
+    if (yAxisCategories && merged.yAxis && typeof merged.yAxis === 'object' && !Array.isArray(merged.yAxis)) {
+      merged.yAxis = {
+        ...(merged.yAxis as Record<string, unknown>),
+        type: 'category',
+        data: yAxisCategories,
+      } as EChartsOption['yAxis'];
+    }
+
+    // 设置系列数据行
+    if (Array.isArray(merged.series)) {
+      merged.series = merged.series.map((s, index) => {
+        const seriesDef = s as Record<string, unknown>;
+        if (shouldUseWholeRows(dataset.tupleKind, seriesDef.type)) {
+          return {
+            ...seriesDef,
+            data: dataset.rows,
+          };
+        }
+        // 每列对应一个系列，取 rows 中对应列的数据
+        const columnData = dataset.rows.map((row) => row[index]);
+        return {
+          ...seriesDef,
+          data: columnData,
+        };
+      });
+    }
+
+    return merged;
+  },
+};

package/node_modules/@fses/workbench-card/src/renderers/chart/echarts-protocol/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview ECharts protocol module entry point — re-exports all public
+ * types, the protocol adapter, and the deep-merge utility.
+ * @author seadon
+ * @created 2026-05-05
+ */
+
+export { EChartsProtocolAdapter } from './adapter';
+export { deepMergeOption } from './merger';
+export * from './types';

package/node_modules/@fses/workbench-card/src/renderers/chart/echarts-protocol/merger.ts

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview ECharts option 深度合并工具 — 将 source 选项深度合并到 target 中
+ * @author seadon
+ * @created 2026-05-05
+ */
+
+import type { EChartsOption } from 'echarts';
+
+/**
+ * 判断给定值是否为普通对象（非数组、非 null、非原始类型）
+ * @param value - 待判断的值
+ * @returns 若为普通对象则返回 true
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * 提取 ECharts 数组元素的稳定身份，用于按系列 id/name 合并补丁。
+ * @param item - 待匹配的数组元素
+ * @returns 可用于匹配的身份值，无法识别时返回 undefined
+ */
+function getMergeIdentity(item: Record<string, unknown>): string | undefined {
+  const identity = item.id ?? item.name;
+  return typeof identity === 'string' && identity.trim() ? identity : undefined;
+}
+
+/**
+ * 按 id/name 或数组下标将 source 数组元素合并进 target，避免 optionPatch 覆盖整组对象数组。
+ * @param target - 已生成的 ECharts 数组选项
+ * @param source - 用户补丁中的数组选项
+ * @returns 合并后的数组
+ */
+function mergeArrayByIdentity(target: unknown[], source: unknown[]): unknown[] {
+  if (source.some((item) => !isPlainObject(item))) {
+    return [...source];
+  }
+  const sourceItems = source as Array<Record<string, unknown>>;
+
+  return sourceItems.reduce<unknown[]>((items, sourceItem, sourceIndex) => {
+    const sourceIdentity = getMergeIdentity(sourceItem);
+    const targetIndex = items.findIndex((targetItem) => (
+      isPlainObject(targetItem)
+      && sourceIdentity
+      && getMergeIdentity(targetItem) === sourceIdentity
+    ));
+
+    if (targetIndex === -1) {
+      const fallbackIndex = isPlainObject(items[sourceIndex]) ? sourceIndex : -1;
+      if (fallbackIndex === -1) return [...items, sourceItem];
+      return items.map((item, itemIndex) => (
+        itemIndex === fallbackIndex
+          ? deepMergeOption(item as EChartsOption, sourceItem)
+          : item
+      ));
+    }
+
+    return items.map((item, itemIndex) => (
+      itemIndex === targetIndex
+        ? deepMergeOption(item as EChartsOption, sourceItem)
+        : item
+    ));
+  }, [...target]);
+}
+
+/**
+ * 判断指定数组选项是否需要按对象元素合并。
+ * @param key - 当前 option 字段名。
+ * @returns 需要保留运行时子字段的对象数组返回 true。
+ */
+function shouldMergeObjectArray(key: string): boolean {
+  return key === 'series' || key === 'xAxis' || key === 'yAxis';
+}
+
+/**
+ * 将 source 深度合并到 target 中，source 中的值覆盖 target 中的同名值。
+ * 递归合并普通对象；series/xAxis/yAxis 对象数组按 id/name 或下标合并，其它数组直接覆盖。
+ * 返回一个新对象，不会修改 target。
+ *
+ * @param target - 目标 ECharts option，作为合并基础
+ * @param source - 源选项对象，其中的值将覆盖 target 中的同名值
+ * @returns 合并后的新 ECharts option 对象
+ */
+export function deepMergeOption(
+  target: EChartsOption,
+  source: Record<string, unknown>,
+): EChartsOption {
+  const result: Record<string, unknown> = { ...target };
+
+  for (const key of Object.keys(source)) {
+    const targetVal = result[key];
+    const sourceVal = source[key];
+
+    if (Array.isArray(targetVal) && Array.isArray(sourceVal) && shouldMergeObjectArray(key)) {
+      result[key] = mergeArrayByIdentity(targetVal, sourceVal);
+    } else if (isPlainObject(targetVal) && isPlainObject(sourceVal)) {
+      // 两者都是普通对象（非数组），递归合并
+      result[key] = deepMergeOption(
+        targetVal as EChartsOption,
+        sourceVal as Record<string, unknown>,
+      );
+    } else {
+      // 原始值、数组或 null/undefined — source 直接覆盖
+      result[key] = sourceVal;
+    }
+  }
+
+  return result as EChartsOption;
+}