@fses/workbench-app 0.1.3 → 0.2.1

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

@@ -0,0 +1,515 @@
+/**
+ * @fileoverview ECharts protocol type definitions — defines the contract between
+ * card payloads, protocol config/data payloads, and converter interfaces used
+ * by the echarts-protocol rendering pipeline.
+ * @author seadon
+ * @created 2026-05-05
+ */
+
+import type { EChartsOption } from 'echarts';
+
+// ---------------------------------------------------------------------------
+// 1. General card protocol types
+// ---------------------------------------------------------------------------
+
+/**
+ * Supported renderer types for card payloads.
+ * Extensible via `string` to allow future renderers without breaking changes.
+ */
+export type RendererType = 'echarts' | 'table' | 'metric' | 'richtext' | 'iframe' | (string & {});
+
+/**
+ * Top-level card payload delivered by the backend pipeline.
+ * Each card carries a renderer type discriminator so the frontend can route
+ * it to the correct renderer component.
+ */
+export interface CardPayload {
+  /** Discriminator that determines which renderer component handles this card */
+  rendererType: RendererType;
+  /** Unique identifier for the card instance */
+  cardId: string;
+  /** Primary display title */
+  title: string;
+  /** Optional secondary description */
+  subtitle?: string;
+  /** Renderer-specific configuration (e.g. ProtocolConfigPayload for echarts) */
+  configPayload: unknown;
+  /** Renderer-specific data (e.g. ProtocolDataPayload for echarts) */
+  dataPayload?: unknown;
+  /** Optional binding ID linking this card to a data source */
+  dataBindingId?: string;
+}
+
+// ---------------------------------------------------------------------------
+// 2. ECharts protocol types
+// ---------------------------------------------------------------------------
+
+/**
+ * The 13 canonical protocol types that describe how chart data is structured.
+ * Each type implies a specific data shape and converter strategy.
+ */
+export type ProtocolType =
+  | 'series'
+  | 'table'
+  | 'tuple'
+  | 'tree'
+  | 'network'
+  | 'geo'
+  | 'scene3D'
+  | 'timeline'
+  | 'transition'
+  | 'graphic'
+  | 'layout'
+  | 'composite'
+  | 'configOnly';
+
+/**
+ * Chart family classification used to group charts by coordinate system.
+ */
+export type ChartFamily = 'cartesian' | 'radial' | 'tree' | 'network' | 'geo' | 'gl' | 'free';
+
+/**
+ * Describes a single series definition within a chart configuration.
+ * Maps one-to-one with ECharts series entries in the generated option.
+ */
+export interface SeriesDef {
+  /** Unique series identifier */
+  id: string;
+  /** ECharts series type (e.g. 'bar', 'line', 'pie') */
+  type: string;
+  /** Optional reference to a dataset the series draws from */
+  datasetId?: string;
+}
+
+// ---------------------------------------------------------------------------
+// 3. Config payload (ProtocolConfigPayload)
+// ---------------------------------------------------------------------------
+
+/**
+ * Static configuration payload that describes how to build the ECharts option.
+ * This is the "skeleton" of the chart — it defines structure but not the data.
+ */
+export interface ProtocolConfigPayload {
+  /** Protocol version for forward compatibility */
+  version: '1.0';
+  /** Discriminator indicating the protocol structure type */
+  protocolType: ProtocolType;
+  /** Unique identifier for the chart this config belongs to */
+  chartId: string;
+  /** Chart metadata */
+  chart: {
+    /** Chart identifier (may differ from chartId when chart is templated) */
+    id: string;
+    /** Human-readable chart title */
+    title: string;
+    /** Chart coordinate family classification */
+    family: ChartFamily;
+    /** Rendering engine */
+    renderer: 'canvas' | 'svg';
+  };
+  /** Series definitions describing each data series in the chart */
+  series: SeriesDef[];
+  /** Presentation configuration for visual elements */
+  presentation: {
+    /** ECharts theme name or theme object */
+    theme?: string | Record<string, unknown>;
+    /** Tooltip configuration */
+    tooltip?: Record<string, unknown>;
+    /** Legend configuration */
+    legend?: Record<string, unknown>;
+    /** Animation configuration */
+    animation?: Record<string, unknown>;
+  };
+  /** Extraction status metadata */
+  extraction?: {
+    /** Current extraction status (e.g. 'complete', 'partial') */
+    status: string;
+  };
+  /** Official ECharts example comparison for reference */
+  officialComparison?: {
+    /** URL to the ECharts editor with the original example */
+    editorUrl: string;
+    /** URL to the source code of the original example */
+    sourceUrl: string;
+  };
+  /** Source replay configuration for reproducing the chart from original examples */
+  officialSourceReplay?: {
+    /** Whether source replay is enabled */
+    enabled: boolean;
+    /** Relative path to the source file */
+    sourceRelativePath: string;
+    /** Root path of the source repository */
+    rootPath: string;
+    /** CDN path for asset resolution */
+    cdnPath: string;
+    /** External dependency requirements */
+    requires: {
+      echartsGl?: boolean;
+      jquery?: boolean;
+      d3?: boolean;
+      ecStat?: boolean;
+      datGui?: boolean;
+    };
+  };
+  /** Arbitrary ECharts option overrides merged on top of the generated option */
+  optionPatch?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// 4. Data payloads (per protocol type)
+// ---------------------------------------------------------------------------
+
+/**
+ * Base fields shared by all protocol data payloads.
+ * Each concrete payload re-declares `protocolType` as a string literal
+ * so TypeScript can discriminate between them in the union type.
+ */
+interface ProtocolDataBase {
+  /** Protocol version for forward compatibility */
+  version: '1.0';
+  /** Unique identifier for the chart this data belongs to */
+  chartId: string;
+  /** Optional parameters passed alongside the data */
+  params?: Record<string, unknown>;
+  /** Reload policy controlling how data updates are handled */
+  reloadPolicy: {
+    /** Reload mode (e.g. 'replace', 'append', 'merge') */
+    mode: string;
+    /** Whether this data type supports refreshing without rebuilding the option */
+    supportsDataOnlyReload: boolean;
+  };
+  /** Extraction metadata */
+  extraction?: {
+    status: string;
+  };
+}
+
+/**
+ * Series protocol data — standard cartesian / radial chart data with
+ * categories on one axis and one or more numeric series.
+ */
+export interface SeriesDataPayload extends ProtocolDataBase {
+  protocolType: 'series';
+  /** Category labels for cartesian x-axis, or radar indicators for radial charts */
+  categories: {
+    xAxis?: string[];
+    indicators?: Array<{ name: string; max?: number }>;
+  };
+  /** Array of data series, each with numeric values */
+  series: Array<{
+    /** Series identifier matching SeriesDef.id */
+    id: string;
+    /** Series display name */
+    name: string;
+    /** Hint for the preferred ECharts series type */
+    typeHint?: string;
+    /** Numeric data values, one per category */
+    data: number[];
+  }>;
+}
+
+/**
+ * Table protocol data — tabular data organized by datasets with dimensions.
+ */
+export interface TableDataPayload extends ProtocolDataBase {
+  protocolType: 'table';
+  /** Array of tabular datasets */
+  datasets: Array<{
+    /** Dataset identifier */
+    id: string;
+    /** Data shape discriminator */
+    shape: 'table';
+    /** Column dimension names */
+    dimensions?: string[];
+    /** Raw data rows (array of arrays) */
+    source: unknown[][];
+    /** Rows as key-value records (optional alternative to source) */
+    rows?: Record<string, unknown>[];
+  }>;
+}
+
+/**
+ * Tuple protocol data — combines categories with tuple-structured rows.
+ */
+export interface TupleDataPayload extends ProtocolDataBase {
+  protocolType: 'tuple';
+  /** Single tuple dataset */
+  dataset: {
+    /** Dataset identifier */
+    id: string;
+    /** Data shape discriminator */
+    shape: 'tuple';
+    /** Kind of tuple encoding */
+    tupleKind: string;
+    /** Column dimension names */
+    dimensions: string[];
+    /** Optional category labels for tuple axes */
+    categories?: { xAxis: string[]; yAxis?: string[] };
+    /** Data rows as arrays */
+    rows: unknown[][];
+  };
+}
+
+/**
+ * Hierarchical tree node used in TreeDataPayload.
+ */
+export interface TreeNode {
+  /** Node display name */
+  name: string;
+  /** Optional numeric value for leaf nodes */
+  value?: number;
+  /** Whether the node starts collapsed */
+  collapsed?: boolean;
+  /** Child nodes */
+  children?: TreeNode[];
+}
+
+/**
+ * Tree protocol data — hierarchical data with nested nodes.
+ */
+export interface TreeDataPayload extends ProtocolDataBase {
+  protocolType: 'tree';
+  /** Single tree dataset */
+  dataset: {
+    /** Dataset identifier */
+    id: string;
+    /** Data shape discriminator */
+    shape: 'tree';
+    /** Root nodes of the tree (multiple roots supported) */
+    roots: TreeNode[];
+  };
+}
+
+/**
+ * Network node used in NetworkDataPayload.
+ */
+export interface NetworkNode {
+  /** Node unique name / identifier */
+  name: string;
+  /** Optional numeric value for sizing */
+  value?: number;
+  /** Optional category index for grouping */
+  category?: number;
+  /** Optional symbol size */
+  symbolSize?: number;
+  /** Additional node properties */
+  [key: string]: unknown;
+}
+
+/**
+ * Network link (edge) used in NetworkDataPayload.
+ */
+export interface NetworkLink {
+  /** Source node name */
+  source: string;
+  /** Target node name */
+  target: string;
+  /** Optional link value for width weighting */
+  value?: number;
+  /** Additional link properties */
+  [key: string]: unknown;
+}
+
+/**
+ * Network protocol data — graph / relationship data with nodes and links.
+ */
+export interface NetworkDataPayload extends ProtocolDataBase {
+  protocolType: 'network';
+  /** Single network dataset */
+  dataset: {
+    /** Dataset identifier */
+    id: string;
+    /** Data shape discriminator */
+    shape: 'network';
+    /** Graph nodes */
+    nodes: NetworkNode[];
+    /** Graph edges / links */
+    links: NetworkLink[];
+    /** Optional category labels for node grouping */
+    categories?: Array<{ name: string }>;
+  };
+}
+
+/**
+ * Geo protocol data — geographic data with regions, points, and lines.
+ */
+export interface GeoDataPayload extends ProtocolDataBase {
+  protocolType: 'geo';
+  /** Single geo dataset */
+  dataset: {
+    /** Dataset identifier */
+    id: string;
+    /** Data shape discriminator */
+    shape: 'geo';
+    /** ECharts map name (e.g. 'china', 'world') */
+    mapName?: string;
+    /** Point data for scatter overlay */
+    points?: unknown[];
+    /** Line data for connection overlay */
+    lines?: unknown[];
+    /** Region data with name-value pairs */
+    regions: Array<{
+      /** Region name matching map geography */
+      name: string;
+      /** Region numeric value for coloring */
+      value: number;
+    }>;
+  };
+}
+
+/**
+ * 3D scene protocol data — data for echarts-gl 3D visualizations.
+ */
+export interface Scene3DDataPayload extends ProtocolDataBase {
+  protocolType: 'scene3D';
+  /** Single 3D scene dataset */
+  dataset: {
+    /** Dataset identifier */
+    id: string;
+    /** Data shape discriminator */
+    shape: 'scene3d';
+    /** Additional 3D-specific data properties */
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Timeline protocol data — data with temporal ordering.
+ */
+export interface TimelineDataPayload extends ProtocolDataBase {
+  protocolType: 'timeline';
+  /** Single timeline dataset */
+  dataset: {
+    /** Dataset identifier */
+    id: string;
+    /** Data shape discriminator */
+    shape: 'timeline';
+    /** Additional timeline-specific data properties */
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Transition protocol data — data for animated state transitions.
+ */
+export interface TransitionDataPayload extends ProtocolDataBase {
+  protocolType: 'transition';
+  /** Single transition dataset */
+  dataset: {
+    /** Dataset identifier */
+    id: string;
+    /** Data shape discriminator */
+    shape: 'transition';
+    /** Additional transition-specific data properties */
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Graphic protocol data — custom graphic elements.
+ */
+export interface GraphicDataPayload extends ProtocolDataBase {
+  protocolType: 'graphic';
+  /** Single graphic dataset */
+  dataset: {
+    /** Dataset identifier */
+    id: string;
+    /** Data shape discriminator */
+    shape: 'graphic';
+    /** Custom graphic element descriptors */
+    elements: unknown[];
+  };
+}
+
+/**
+ * Layout protocol data — grid / dashboard layout descriptors.
+ */
+export interface LayoutDataPayload extends ProtocolDataBase {
+  protocolType: 'layout';
+  /** Single layout dataset */
+  dataset: {
+    /** Dataset identifier */
+    id: string;
+    /** Data shape discriminator */
+    shape: 'layout';
+    /** Grid layout descriptors */
+    grids: unknown[];
+  };
+}
+
+/**
+ * Composite protocol data — mixed / multi-chart composites.
+ */
+export interface CompositeDataPayload extends ProtocolDataBase {
+  protocolType: 'composite';
+  /** Single composite dataset */
+  dataset: {
+    /** Dataset identifier */
+    id: string;
+    /** Data shape discriminator */
+    shape: 'composite';
+    /** Additional composite-specific data properties */
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Config-only protocol data — charts that carry no external data
+ * (all data is embedded in the config option).
+ */
+export interface ConfigOnlyDataPayload extends ProtocolDataBase {
+  protocolType: 'configOnly';
+  /** Placeholder dataset with no actual data */
+  dataset: {
+    /** Shape discriminator indicating no data payload */
+    shape: 'none';
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 5. Union type
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union of all 13 protocol data payloads.
+ * Use `payload.protocolType` to narrow to the specific type.
+ */
+export type ProtocolDataPayload =
+  | SeriesDataPayload
+  | TableDataPayload
+  | TupleDataPayload
+  | TreeDataPayload
+  | NetworkDataPayload
+  | GeoDataPayload
+  | Scene3DDataPayload
+  | TimelineDataPayload
+  | TransitionDataPayload
+  | GraphicDataPayload
+  | LayoutDataPayload
+  | CompositeDataPayload
+  | ConfigOnlyDataPayload;
+
+// ---------------------------------------------------------------------------
+// 6. Converter interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Converter interface that transforms protocol payloads into ECharts options.
+ * Each protocol type should have its own implementation of this interface.
+ */
+export interface ProtocolConverter {
+  /**
+   * Build a complete ECharts option from the config payload.
+   * @param config - The protocol configuration describing chart structure
+   * @returns A fully-formed ECharts option ready for rendering
+   */
+  buildOption(config: ProtocolConfigPayload): EChartsOption;
+
+  /**
+   * Merge data payload into an existing ECharts option without rebuilding it.
+   * @param option - The existing ECharts option to update
+   * @param data - The protocol data payload to merge
+   * @returns The updated ECharts option
+   */
+  mergeData(option: EChartsOption, data: ProtocolDataPayload): EChartsOption;
+}