transone-chart 0.1.2

package/lib/core/chart.ts

@@ -0,0 +1,322 @@
+/**
+ * ChartBase：所有图表的抽象基类，负责统一渲染管线。
+ *
+ * 渲染管线（render）：
+ *   save → scale(dpr) → clear → 背景 → 布局计算
+ *     → 标题 → 图例 → 笛卡尔坐标轴（折线/柱状）
+ *     → drawSeries（子类策略） → restore
+ *
+ * 生命周期：setOption 增量更新 → render；resize 改逻辑尺寸 → render；
+ * destroy 释放。所有坐标均为逻辑像素（CSS px），DPR 由管线统一缩放。
+ */
+
+import type { ICanvas2D } from './canvas';
+import { AxisDrawer } from './axis';
+import {
+  computeLayout,
+  type LayoutInput,
+  type LayoutResult,
+} from './layout';
+import { LegendDrawer, type LegendItem } from './legend';
+import { CategoryScale, LinearScale } from './scale';
+import { applyFont, measureWidth } from './text';
+import {
+  DEFAULT_PALETTE,
+  type CategoryAxisOption,
+  type ChartOption,
+  type ChartRenderContext,
+  type LegendOption,
+  type TitleOption,
+  type ValueAxisOption,
+} from '../types';
+
+export interface CartesianScales {
+  value: LinearScale;
+  category: CategoryScale;
+}
+
+/**
+ * 子类需要实现的钩子：
+ * - drawSeries：绘制数据系列（核心策略）
+ * - hasCartesianAxis：是否需要坐标轴（饼图/雷达返回 false）
+ * - getValueDomain：数值轴数据域（有轴时）
+ * - getCategoryLabels：类目轴标签（有轴时）
+ * - isHorizontal：横向布局（横向柱状图）
+ */
+export abstract class ChartBase<T extends ChartOption> {
+  protected readonly ctx: ICanvas2D;
+  protected option: T;
+  protected width: number;
+  protected height: number;
+  protected dpr: number;
+  protected readonly palette: readonly string[];
+
+  /** 每次 render 构建的笛卡尔比例尺，供 drawSeries 读取。 */
+  protected cartesian: CartesianScales | null = null;
+
+  private destroyed = false;
+
+  public constructor(context: ChartRenderContext, option: T) {
+    this.ctx = context.ctx;
+    this.option = option;
+    this.width = context.width;
+    this.height = context.height;
+    this.dpr = context.dpr;
+    this.palette = context.palette ?? DEFAULT_PALETTE;
+  }
+
+  /* —— 生命周期 —— */
+
+  public setOption(option: Partial<T>): this {
+    this.option = { ...this.option, ...option };
+    return this;
+  }
+
+  public resize(width: number, height: number): this {
+    this.width = Math.max(0, width);
+    this.height = Math.max(0, height);
+    return this;
+  }
+
+  public render(): this {
+    if (this.destroyed) {
+      return this;
+    }
+    const { ctx, width, height, dpr } = this;
+
+    ctx.save();
+    ctx.scale(dpr, dpr);
+    ctx.clearRect(0, 0, width, height);
+
+    const background = this.getBackgroundColor();
+    if (background) {
+      ctx.fillStyle = background;
+      ctx.fillRect(0, 0, width, height);
+    }
+
+    const layout = this.computeLayout();
+    this.drawTitle(layout);
+    this.drawLegend(layout);
+
+    if (this.hasCartesianAxis()) {
+      this.cartesian = this.buildCartesianScales(layout);
+      this.drawCartesianAxis(layout);
+    } else {
+      this.cartesian = null;
+    }
+
+    this.drawSeries(ctx, layout, this.option);
+
+    ctx.restore();
+    return this;
+  }
+
+  public destroy(): void {
+    this.destroyed = true;
+  }
+
+  public isDestroyed(): boolean {
+    return this.destroyed;
+  }
+
+  /* —— 子类策略钩子 —— */
+
+  protected abstract drawSeries(
+    ctx: ICanvas2D,
+    layout: LayoutResult,
+    option: T
+  ): void;
+
+  protected hasCartesianAxis(): boolean {
+    return true;
+  }
+
+  protected getValueDomain(): { min: number; max: number } {
+    return { min: 0, max: 1 };
+  }
+
+  protected getCategoryLabels(): readonly string[] {
+    return [];
+  }
+
+  protected isHorizontal(): boolean {
+    return false;
+  }
+
+  /* —— 可覆盖的配置来源 —— */
+
+  protected getBackgroundColor(): string | undefined {
+    return (this.option as { backgroundColor?: string }).backgroundColor;
+  }
+
+  protected getTitle(): TitleOption | undefined {
+    return (this.option as { title?: TitleOption }).title;
+  }
+
+  protected getLegend(): LegendOption | undefined {
+    const legend = (this.option as { legend?: LegendOption }).legend;
+    if (legend) {
+      return legend;
+    }
+    // 未显式配置图例但存在命名系列/扇区时，默认在顶部显示
+    return this.getLegendItems().length > 0 ? { position: 'top' } : undefined;
+  }
+
+  protected getLegendItems(): LegendItem[] {
+    return [];
+  }
+
+  protected getValueAxis(): ValueAxisOption | undefined {
+    return (this.option as { yAxis?: ValueAxisOption }).yAxis;
+  }
+
+  protected getCategoryAxis(): CategoryAxisOption | undefined {
+    return (this.option as { xAxis?: CategoryAxisOption }).xAxis;
+  }
+
+  /* —— 渲染管线内部 —— */
+
+  protected computeLayout(): LayoutResult {
+    const input = this.buildLayoutInput();
+    const measure = (text: string): number =>
+      measureWidth(this.ctx, text, 11);
+    return computeLayout(input, measure);
+  }
+
+  protected buildLayoutInput(): LayoutInput {
+    // 轴标签区需要知道刻度标签宽度，而刻度与布局无关（仅依赖数据域），
+    // 因此用占位 range 预计算刻度 → 布局 → 最终 scale 两阶段完成。
+    const horizontal = this.isHorizontal();
+    const hasAxis = this.hasCartesianAxis();
+    return {
+      width: this.width,
+      height: this.height,
+      title: this.getTitle(),
+      legend: this.getLegend(),
+      legendItems: this.getLegendItems().map((item) => item.name),
+      valueLabels: hasAxis && !horizontal ? this.computeValueLabels() : undefined,
+      categoryLabels: hasAxis ? this.getCategoryLabels() : undefined,
+      horizontal,
+    };
+  }
+
+  /** 用占位 range 预计算数值刻度标签（仅用于测量，不参与最终映射）。 */
+  protected computeValueLabels(): string[] {
+    const domain = this.getValueDomain();
+    const valueAxis = this.getValueAxis();
+    const probe = new LinearScale(domain.min, domain.max, 0, 1, {
+      min: valueAxis?.min,
+      max: valueAxis?.max,
+      splitCount: valueAxis?.splitCount,
+    });
+    return probe.ticks.map((tick) =>
+      valueAxis?.format ? valueAxis.format(tick) : String(tick)
+    );
+  }
+
+  protected drawTitle(layout: LayoutResult): void {
+    const title = this.getTitle();
+    if (!title?.text || !layout.titleBox) {
+      return;
+    }
+    const { ctx } = this;
+    applyFont(ctx, title.fontSize ?? 16);
+    ctx.fillStyle = title.color ?? '#323233';
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'top';
+    ctx.fillText(title.text, this.width / 2, layout.titleBox.y);
+  }
+
+  protected drawLegend(layout: LayoutResult): void {
+    const legend = this.getLegend();
+    if (legend?.show === false || !layout.legendBox) {
+      return;
+    }
+    const items = this.getLegendItems();
+    if (items.length === 0) {
+      return;
+    }
+    new LegendDrawer(this.ctx).draw({
+      box: layout.legendBox,
+      items,
+      position: legend?.position ?? 'top',
+      fontSize: legend?.fontSize,
+      color: legend?.color,
+      markerSize: legend?.markerSize,
+      itemGap: legend?.itemGap,
+    });
+  }
+
+  protected buildCartesianScales(layout: LayoutResult): CartesianScales {
+    const { plot } = layout;
+    const horizontal = this.isHorizontal();
+    const domain = this.getValueDomain();
+    const categories = this.getCategoryLabels();
+    const valueAxis = this.getValueAxis();
+
+    const value = new LinearScale(
+      domain.min,
+      domain.max,
+      horizontal ? plot.x : plot.y + plot.height,
+      horizontal ? plot.x + plot.width : plot.y,
+      { min: valueAxis?.min, max: valueAxis?.max, splitCount: valueAxis?.splitCount }
+    );
+
+    const category = new CategoryScale(
+      categories,
+      horizontal ? plot.y : plot.x,
+      horizontal ? plot.y + plot.height : plot.x + plot.width
+    );
+
+    return { value, category };
+  }
+
+  protected drawCartesianAxis(layout: LayoutResult): void {
+    const scales = this.cartesian;
+    if (!scales) {
+      return;
+    }
+    const { ctx } = this;
+    const { plot } = layout;
+    const horizontal = this.isHorizontal();
+    const valueAxis = this.getValueAxis();
+    const categoryAxis = this.getCategoryAxis();
+    const categories = this.getCategoryLabels();
+
+    const drawer = new AxisDrawer(ctx);
+
+    const valueLabels = scales.value.ticks.map((tick) =>
+      valueAxis?.format ? valueAxis.format(tick) : String(tick)
+    );
+
+    drawer.drawValueAxis({
+      plot,
+      scale: scales.value,
+      labels: valueLabels,
+      horizontal,
+      labelFontSize: valueAxis?.labelFontSize,
+      labelColor: valueAxis?.labelColor,
+      gridColor: valueAxis?.gridColor,
+      gridLineWidth: valueAxis?.gridLineWidth,
+      gridLineDash: valueAxis?.gridLineDash,
+      showGrid: valueAxis?.showGrid ?? true,
+    });
+
+    drawer.drawCategoryAxis({
+      plot,
+      scale: scales.category,
+      labels: categories,
+      horizontal,
+      labelFontSize: categoryAxis?.labelFontSize,
+      labelColor: categoryAxis?.labelColor,
+      gridColor: categoryAxis?.gridColor,
+      gridLineWidth: categoryAxis?.gridLineWidth,
+      showGrid: categoryAxis?.showGrid ?? false,
+    });
+  }
+
+  /** 系列取色：显式 color 优先，否则按索引取色板。 */
+  protected seriesColor(index: number, color?: string): string {
+    return color ?? this.palette[index % this.palette.length];
+  }
+}

package/lib/core/layout.ts

@@ -0,0 +1,221 @@
+/**
+ * 图表布局计算：在给定画布尺寸内，按 title / legend / 坐标轴标签区
+ * 逐层扣除，得到最终绘图区（plot）。
+ *
+ * 布局只依赖注入的文本测量函数，不接触 Canvas 上下文本身，
+ * 保持纯逻辑可测。
+ */
+
+import type { LegendOption, TitleOption } from '../types';
+
+export interface Box {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface Padding {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export interface LayoutInput {
+  width: number;
+  height: number;
+  title?: TitleOption;
+  /** 图例配置（已解析 show/position）。 */
+  legend?: LegendOption;
+  /** 图例项名称列表（用于测量总宽度）。 */
+  legendItems?: readonly string[];
+  /** 数值轴刻度标签（测量最大宽度）。 */
+  valueLabels?: readonly string[];
+  /** 类目轴标签（测量最大宽度/高度）。 */
+  categoryLabels?: readonly string[];
+  /** 横向布局（横向柱状图）：类目轴占左侧、数值轴占底部。 */
+  horizontal?: boolean;
+  /** 基础内边距，默认 { top: 12, right: 16, bottom: 12, left: 16 }。 */
+  basePadding?: Partial<Padding>;
+}
+
+export interface LayoutResult {
+  /** 绘图区（含网格与数据系列）。 */
+  plot: Box;
+  /** 数值轴标签区（横轴图中在左侧，横向图中在底部）。 */
+  valueAxisBox: Box;
+  /** 类目轴标签区（横轴图中在底部，横向图中在左侧）。 */
+  categoryAxisBox: Box;
+  /** 标题占用区（若存在）。 */
+  titleBox: Box | null;
+  /** 图例占用区（若存在）。 */
+  legendBox: Box | null;
+  padding: Padding;
+}
+
+export type MeasureTextFn = (text: string) => number;
+
+const DEFAULT_PADDING: Padding = { top: 12, right: 16, bottom: 12, left: 16 };
+const TITLE_PADDING = 16;
+const AXIS_LABEL_PADDING = 8;
+const LEGEND_PADDING = 12;
+
+/** 计算图例占用的行高（top/bottom 单行）或列宽（right 纵向）。 */
+function measureLegend(
+  input: LayoutInput,
+  measure: MeasureTextFn
+): { width: number; height: number } {
+  const { legend } = input;
+  const items = input.legendItems ?? [];
+  const fontSize = legend?.fontSize ?? 12;
+  const itemGap = legend?.itemGap ?? 16;
+  const markerSize = legend?.markerSize ?? 12;
+
+  if (legend?.position === 'right') {
+    // 纵向：宽度 = 最宽项（色块 + 间距 + 文本），高度 = 项数 × 行高
+    let maxWidth = 0;
+    for (const item of items) {
+      const w = markerSize + 6 + measure(item);
+      if (w > maxWidth) {
+        maxWidth = w;
+      }
+    }
+    return {
+      width: maxWidth + LEGEND_PADDING,
+      height: Math.max(items.length * (fontSize + 8) + LEGEND_PADDING, 0),
+    };
+  }
+
+  // 横向：单行居中，总宽 = 各项宽之和
+  let totalWidth = 0;
+  for (const item of items) {
+    totalWidth += markerSize + 6 + measure(item) + itemGap;
+  }
+  if (totalWidth > 0) {
+    totalWidth -= itemGap;
+  }
+  return { width: totalWidth, height: fontSize + LEGEND_PADDING + 4 };
+}
+
+/**
+ * 计算完整布局。规则：
+ * - title 固定顶部
+ * - legend：top → title 之下；bottom → 底部；right → 最右侧
+ * - 数值轴标签区与类目轴标签区按 horizontal 互换左右/底部
+ */
+export function computeLayout(
+  input: LayoutInput,
+  measure: MeasureTextFn
+): LayoutResult {
+  const padding: Padding = { ...DEFAULT_PADDING, ...input.basePadding };
+
+  let top = padding.top;
+  let bottom = padding.bottom;
+  let left = padding.left;
+  let right = padding.right;
+
+  let titleBox: Box | null = null;
+  if (input.title?.text) {
+    const fontSize = input.title.fontSize ?? 16;
+    titleBox = { x: 0, y: 0, width: input.width, height: fontSize };
+    top += fontSize + (input.title.padding ?? TITLE_PADDING);
+  }
+
+  let legendBox: Box | null = null;
+  const legend = input.legend;
+  if (legend && legend.show !== false && (input.legendItems?.length ?? 0) > 0) {
+    const size = measureLegend(input, measure);
+    const position = legend.position ?? 'top';
+    if (position === 'top') {
+      legendBox = {
+        x: 0,
+        y: titleBox ? titleBox.height : 0,
+        width: input.width,
+        height: size.height,
+      };
+      top += size.height;
+    } else if (position === 'bottom') {
+      legendBox = {
+        x: 0,
+        y: input.height - size.height,
+        width: input.width,
+        height: size.height,
+      };
+      bottom += size.height;
+    } else {
+      legendBox = {
+        x: input.width - size.width,
+        y: top,
+        width: size.width,
+        height: Math.max(0, input.height - top - bottom),
+      };
+      right += size.width;
+    }
+  }
+
+  // 坐标轴标签区
+  const labelFontSize = 11;
+  let valueAxisWidth = 0;
+  let categoryAxisHeight = 0;
+  let valueAxisHeight = 0;
+  let categoryAxisWidth = 0;
+
+  const valueLabels = input.valueLabels ?? [];
+  const categoryLabels = input.categoryLabels ?? [];
+
+  if (input.horizontal) {
+    // 横向图：类目轴在左侧（列宽），数值轴在底部（行高）
+    if (categoryLabels.length > 0) {
+      for (const label of categoryLabels) {
+        const w = measure(label);
+        if (w > categoryAxisWidth) {
+          categoryAxisWidth = w;
+        }
+      }
+      categoryAxisWidth += AXIS_LABEL_PADDING * 2;
+      left += categoryAxisWidth;
+    }
+    if (valueLabels.length > 0) {
+      valueAxisHeight = labelFontSize + AXIS_LABEL_PADDING * 2;
+      bottom += valueAxisHeight;
+    }
+  } else {
+    if (valueLabels.length > 0) {
+      for (const label of valueLabels) {
+        const w = measure(label);
+        if (w > valueAxisWidth) {
+          valueAxisWidth = w;
+        }
+      }
+      valueAxisWidth += AXIS_LABEL_PADDING * 2;
+      left += valueAxisWidth;
+    }
+    if (categoryLabels.length > 0) {
+      categoryAxisHeight = labelFontSize + AXIS_LABEL_PADDING * 2;
+      bottom += categoryAxisHeight;
+    }
+  }
+
+  const plotWidth = Math.max(0, input.width - left - right);
+  const plotHeight = Math.max(0, input.height - top - bottom);
+
+  const plot: Box = { x: left, y: top, width: plotWidth, height: plotHeight };
+
+  const valueAxisBox: Box = input.horizontal
+    ? { x: plot.x, y: plot.y + plot.height, width: plotWidth, height: valueAxisHeight }
+    : { x: plot.x - valueAxisWidth, y: top, width: valueAxisWidth, height: plotHeight };
+
+  const categoryAxisBox: Box = input.horizontal
+    ? { x: plot.x - categoryAxisWidth, y: top, width: categoryAxisWidth, height: plotHeight }
+    : { x: left, y: plot.y + plotHeight, width: plotWidth, height: categoryAxisHeight };
+
+  return {
+    plot,
+    valueAxisBox,
+    categoryAxisBox,
+    titleBox,
+    legendBox,
+    padding,
+  };
+}

package/lib/core/legend.ts

@@ -0,0 +1,94 @@
+/**
+ * 图例绘制：色块 + 文本。
+ * - top / bottom：横向单行居中排布
+ * - right：纵向排布
+ */
+
+import type { ICanvas2D } from './canvas';
+import type { Box } from './layout';
+import { applyFont, measureWidth } from './text';
+import { DEFAULT_TEXT_COLOR } from '../types';
+
+export interface LegendItem {
+  name: string;
+  color: string;
+}
+
+export interface LegendDrawOptions {
+  box: Box;
+  items: readonly LegendItem[];
+  position?: 'top' | 'bottom' | 'right';
+  fontSize?: number;
+  color?: string;
+  markerSize?: number;
+  itemGap?: number;
+}
+
+export class LegendDrawer {
+  public constructor(private readonly ctx: ICanvas2D) {}
+
+  public draw(options: LegendDrawOptions): void {
+    const {
+      box,
+      items,
+      position = 'top',
+      fontSize = 12,
+      color = DEFAULT_TEXT_COLOR,
+      markerSize = 12,
+      itemGap = 16,
+    } = options;
+
+    if (items.length === 0) {
+      return;
+    }
+
+    const { ctx } = this;
+    applyFont(ctx, fontSize);
+
+    if (position === 'right') {
+      // 纵向：从顶部开始逐项排列
+      let y = box.y + fontSize / 2 + 4;
+      for (const item of items) {
+        this.drawItem(item, box.x, y, fontSize, markerSize, color);
+        y += fontSize + 8;
+      }
+      return;
+    }
+
+    // 横向：居中排布
+    let totalWidth = 0;
+    for (const item of items) {
+      totalWidth += markerSize + 6 + measureWidth(ctx, item.name, fontSize) + itemGap;
+    }
+    totalWidth -= itemGap;
+
+    let x = box.x + (box.width - totalWidth) / 2;
+    const y = box.y + box.height / 2;
+
+    for (const item of items) {
+      this.drawItem(item, x, y, fontSize, markerSize, color);
+      x += markerSize + 6 + measureWidth(ctx, item.name, fontSize) + itemGap;
+    }
+  }
+
+  private drawItem(
+    item: LegendItem,
+    x: number,
+    centerY: number,
+    _fontSize: number,
+    markerSize: number,
+    color: string
+  ): void {
+    const { ctx } = this;
+    // 色块
+    ctx.fillStyle = item.color;
+    ctx.beginPath();
+    ctx.rect(x, centerY - markerSize / 2, markerSize, markerSize);
+    ctx.fill();
+    // 文本
+    ctx.fillStyle = color;
+    ctx.textAlign = 'left';
+    ctx.textBaseline = 'middle';
+    ctx.fillText(item.name, x + markerSize + 6, centerY);
+  }
+}