@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

package/src/charts/bar/compute.ts

@@ -0,0 +1,539 @@
+/**
+ * Bar chart (horizontal) mark computation.
+ *
+ * Takes a normalized chart spec with resolved scales and produces
+ * RectMark[] for rendering horizontal bars. Supports grouped and
+ * stacked variants via the color encoding channel.
+ */
+
+import type {
+  ConditionalValueDef,
+  DataRow,
+  Encoding,
+  GradientDef,
+  LayoutStrategy,
+  LinearGradient,
+  MarkAria,
+  Rect,
+  RectMark,
+} from '@opendata-ai/openchart-core';
+import { isGradientDef, NARROW_VIEWPORT_MAX } from '@opendata-ai/openchart-core';
+import type { ScaleBand, ScaleLinear } from 'd3-scale';
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import { isConditionalValueDef, resolveConditionalValue } from '../../transforms/conditional';
+import { formatLabelValue } from '../_shared/format-label-value';
+import { getColor, getSequentialColor, groupByField } from '../utils';
+
+/**
+ * Auto-orient a gradient for horizontal bars.
+ *
+ * If the gradient uses the default top-to-bottom direction (no explicit
+ * x1/y1/x2/y2, or the defaults x1:0, y1:0, x2:0, y2:1), rotate it to
+ * left-to-right so the gradient follows the bar's data direction.
+ *
+ * Gradients with explicit non-default coordinates are left unchanged.
+ */
+function orientGradientForHorizontalBar(grad: GradientDef): GradientDef {
+  if (grad.gradient !== 'linear') return grad;
+  const lg = grad as LinearGradient;
+  // Only auto-orient if using the default vertical direction.
+  // Default is x1:0, y1:0, x2:0, y2:1 (top-to-bottom).
+  const isDefaultVertical =
+    (lg.x1 === undefined || lg.x1 === 0) &&
+    (lg.y1 === undefined || lg.y1 === 0) &&
+    (lg.x2 === undefined || lg.x2 === 0) &&
+    (lg.y2 === undefined || lg.y2 === 1);
+  if (!isDefaultVertical) return grad;
+  return { ...lg, x1: 0, y1: 0, x2: 1, y2: 0 };
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MIN_BAR_WIDTH = 1;
+
+/**
+ * Readable floor (px) for a single grouped-bar thickness. Value labels render at
+ * fontSize 10 with ~12px line height; below this a bar is thinner than its own
+ * label and the chart reads as stripes (observed on iOS at 375-430px). When
+ * grouped sub-bars would fall under this, we reclaim the band scale's reserved
+ * inter-category whitespace (step - bandwidth) before letting bars shrink,
+ * trading padding for legibility rather than inventing extra height.
+ */
+const MIN_GROUPED_BAR_THICKNESS = 8;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute horizontal bar marks from a normalized chart spec.
+ *
+ * Y axis uses a band scale for categories. X axis uses a linear scale
+ * for values. When a color encoding is present, bars within each category
+ * are grouped (subdivided bands) or stacked (cumulative widths).
+ */
+export function computeBarMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  _chartArea: Rect,
+  _strategy: LayoutStrategy,
+  containerWidth: number,
+): RectMark[] {
+  const encoding = spec.encoding as Encoding;
+  const xChannel = encoding.x;
+  const yChannel = encoding.y;
+
+  if (!xChannel || !yChannel || !scales.x || !scales.y) {
+    return [];
+  }
+
+  const yScale = scales.y.scale as ScaleBand<string>;
+  const xScale = scales.x.scale as ScaleLinear<number, number>;
+
+  // Band scale should provide bandwidth
+  if (typeof yScale.bandwidth !== 'function') {
+    return [];
+  }
+
+  const bandwidth = yScale.bandwidth();
+  // Baseline = pixel x where the bar's left edge anchors. When the x-domain
+  // includes zero (the common case), this is xScale(0). When the domain
+  // excludes zero (explicit non-zero domain or scale.zero: false), xScale(0)
+  // would extrapolate outside the plot area and overrun the y-axis labels, so
+  // anchor to the domain minimum (the plot-area left edge) instead.
+  const xDomain = xScale.domain() as [number, number];
+  const xIncludesZero = xDomain[0] <= 0 && xDomain[1] >= 0;
+  const baseline = xIncludesZero ? xScale(0) : xScale(xDomain[0]);
+  const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
+  const conditionalColor =
+    encoding.color && isConditionalValueDef(encoding.color)
+      ? (encoding.color as ConditionalValueDef)
+      : undefined;
+  const colorField = colorEnc?.field;
+  const isSequentialColor = colorEnc?.type === 'quantitative';
+
+  let marks: RectMark[];
+
+  // If no color encoding, or sequential color (value-based gradient), render simple bars
+  if (!colorField || isSequentialColor) {
+    marks = computeSimpleBars(
+      spec.data,
+      xChannel.field,
+      yChannel.field,
+      xScale,
+      yScale,
+      bandwidth,
+      baseline,
+      scales,
+      isSequentialColor,
+      conditionalColor,
+    );
+  } else {
+    // Color encoding present: decide between colored simple bars vs stacked
+    const categoryGroups = groupByField(spec.data, yChannel.field);
+    const needsStacking = Array.from(categoryGroups.values()).some((rows) => rows.length > 1);
+
+    if (needsStacking) {
+      // stack: undefined/true/'zero'/'normalize'/'center' -> stacked (default); null/false -> grouped
+      const stackEnabled = xChannel.stack !== null && xChannel.stack !== false;
+
+      if (!stackEnabled) {
+        marks = computeGroupedBars(
+          spec.data,
+          xChannel.field,
+          yChannel.field,
+          colorField,
+          xScale,
+          yScale,
+          bandwidth,
+          baseline,
+          scales,
+          containerWidth,
+        );
+      } else {
+        const stackMode =
+          xChannel.stack === 'normalize'
+            ? 'normalize'
+            : xChannel.stack === 'center'
+              ? 'center'
+              : 'zero';
+
+        marks = computeStackedBars(
+          spec.data,
+          xChannel.field,
+          yChannel.field,
+          colorField,
+          xScale,
+          yScale,
+          bandwidth,
+          baseline,
+          scales,
+          stackMode,
+        );
+      }
+    } else {
+      // Single row per category: render like simple bars but with color from scale
+      marks = computeColoredBars(
+        spec.data,
+        xChannel.field,
+        yChannel.field,
+        colorField,
+        xScale,
+        yScale,
+        bandwidth,
+        baseline,
+        scales,
+      );
+    }
+  }
+
+  // Stamp identity keys for data-update transitions
+  const categoryField = yChannel.field;
+  stampBarKeys(marks, categoryField, colorField);
+
+  return applyMarkDefOverrides(marks, spec, bandwidth);
+}
+
+/** Stamp stable identity keys on bar marks for data-update transitions. */
+function stampBarKeys(marks: RectMark[], categoryField: string, colorField?: string): void {
+  const rawKeys = marks.map((m) => {
+    const series = colorField ? String(m.data[colorField] ?? '') : '';
+    const cat = serializeKeyValue(m.data[categoryField]);
+    return `${series}|${cat}`;
+  });
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+}
+
+/** Compute stacked horizontal bars with support for zero/normalize/center modes. */
+function computeStackedBars(
+  data: DataRow[],
+  valueField: string,
+  categoryField: string,
+  colorField: string,
+  xScale: ScaleLinear<number, number>,
+  yScale: ScaleBand<string>,
+  bandwidth: number,
+  _baseline: number,
+  scales: ResolvedScales,
+  stackMode: 'zero' | 'normalize' | 'center' = 'zero',
+): RectMark[] {
+  const marks: RectMark[] = [];
+  const categoryGroups = groupByField(data, categoryField);
+
+  for (const [category, rows] of categoryGroups) {
+    const bandY = yScale(category);
+    if (bandY === undefined) continue;
+
+    // Compute category total for normalize/center modes
+    let categoryTotal = 0;
+    for (const row of rows) {
+      const v = Number(row[valueField] ?? 0);
+      if (Number.isFinite(v) && v > 0) categoryTotal += v;
+    }
+
+    // For center mode, offset so the stack is centered around zero
+    let cumulativeValue = stackMode === 'center' ? -categoryTotal / 2 : 0;
+
+    for (const row of rows) {
+      const groupKey = String(row[colorField] ?? '');
+      const rawValue = Number(row[valueField] ?? 0);
+      // Only stack positive values (same approach as stacked columns)
+      if (!Number.isFinite(rawValue) || rawValue <= 0) continue;
+
+      // For normalize mode, scale the value to a fraction of the total
+      const value =
+        stackMode === 'normalize' && categoryTotal > 0 ? rawValue / categoryTotal : rawValue;
+
+      const color = getColor(scales, groupKey);
+
+      const xLeft = xScale(cumulativeValue);
+      const xRight = xScale(cumulativeValue + value);
+      const barWidth = Math.max(Math.abs(xRight - xLeft), MIN_BAR_WIDTH);
+
+      const aria: MarkAria = {
+        label: `${category}, ${groupKey}: ${formatLabelValue(rawValue)}`,
+      };
+
+      marks.push({
+        type: 'rect',
+        x: Math.min(xLeft, xRight),
+        y: bandY,
+        width: barWidth,
+        height: bandwidth,
+        fill: isGradientDef(color) ? orientGradientForHorizontalBar(color) : color,
+        cornerRadius: 0,
+        data: row as Record<string, unknown>,
+        aria,
+        orient: 'horizontal',
+        stackGroup: category,
+      });
+
+      cumulativeValue += value;
+    }
+  }
+
+  return marks;
+}
+
+/** Compute grouped (dodged) horizontal bars -- side-by-side within each category band. */
+function computeGroupedBars(
+  data: DataRow[],
+  valueField: string,
+  categoryField: string,
+  colorField: string,
+  xScale: ScaleLinear<number, number>,
+  yScale: ScaleBand<string>,
+  bandwidth: number,
+  baseline: number,
+  scales: ResolvedScales,
+  containerWidth: number,
+): RectMark[] {
+  const marks: RectMark[] = [];
+  const categoryGroups = groupByField(data, categoryField);
+
+  // Build a stable group order from first appearance in data (Map for O(1) lookup)
+  const groupIndexMap = new Map<string, number>();
+  for (const row of data) {
+    const key = String(row[colorField] ?? '');
+    if (!groupIndexMap.has(key)) {
+      groupIndexMap.set(key, groupIndexMap.size);
+    }
+  }
+  const groupCount = groupIndexMap.size;
+  if (groupCount === 0) return marks;
+
+  // Subdivide the band height by group count with a small gap.
+  const gap = Math.min(1, bandwidth * 0.05);
+  let groupHeight = bandwidth;
+  let subBandHeight = (groupHeight - gap * (groupCount - 1)) / groupCount;
+
+  // At tight bandwidths sub-bars fall below the readable floor and read as
+  // stripes. The band scale reserves whitespace between categories (step -
+  // bandwidth); reclaim it by growing the group height toward the full step
+  // before letting bars shrink. Bars stay centered in the band so the widened
+  // group doesn't touch its neighbors. A one-pixel residual keeps adjacent
+  // categories visually separable even at full reclaim.
+  //
+  // Gated to narrow containers (< NARROW_VIEWPORT_MAX): the fix targets phones
+  // where this was observed. Gating on the container width (not the derived plot
+  // width) keeps desktop embeds pixel-identical even when a wide container's
+  // left gutter shrinks the plot below 500px.
+  const step = typeof yScale.step === 'function' ? yScale.step() : bandwidth;
+  const maxGroupHeight = Math.max(bandwidth, step - MIN_BAR_WIDTH);
+  if (
+    containerWidth < NARROW_VIEWPORT_MAX &&
+    subBandHeight < MIN_GROUPED_BAR_THICKNESS &&
+    maxGroupHeight > bandwidth
+  ) {
+    const needed = MIN_GROUPED_BAR_THICKNESS * groupCount + gap * (groupCount - 1);
+    groupHeight = Math.min(Math.max(groupHeight, needed), maxGroupHeight);
+    subBandHeight = (groupHeight - gap * (groupCount - 1)) / groupCount;
+  }
+  subBandHeight = Math.max(subBandHeight, MIN_BAR_WIDTH);
+  // Center the (possibly widened) group within the band.
+  const groupOffset = (bandwidth - groupHeight) / 2;
+
+  for (const [category, rows] of categoryGroups) {
+    const bandY = yScale(category);
+    if (bandY === undefined) continue;
+
+    for (const row of rows) {
+      const groupKey = String(row[colorField] ?? '');
+      const value = Number(row[valueField] ?? 0);
+      if (!Number.isFinite(value)) continue;
+
+      const groupIndex = groupIndexMap.get(groupKey) ?? 0;
+      const color = getColor(scales, groupKey);
+      const xPos = value >= 0 ? baseline : xScale(value);
+      const barWidth = Math.max(Math.abs(xScale(value) - baseline), MIN_BAR_WIDTH);
+      const subY = bandY + groupOffset + groupIndex * (subBandHeight + gap);
+
+      const aria: MarkAria = {
+        label: `${category}, ${groupKey}: ${formatLabelValue(value)}`,
+      };
+
+      marks.push({
+        type: 'rect',
+        x: xPos,
+        y: subY,
+        width: barWidth,
+        height: subBandHeight,
+        fill: isGradientDef(color) ? orientGradientForHorizontalBar(color) : color,
+        cornerRadius: 2,
+        data: row as Record<string, unknown>,
+        aria,
+        orient: 'horizontal',
+      });
+    }
+  }
+
+  return marks;
+}
+
+/** Compute colored (non-stacked) horizontal bars. Used when color encoding
+ *  is present but each category has only one row (e.g., diverging charts). */
+function computeColoredBars(
+  data: DataRow[],
+  valueField: string,
+  categoryField: string,
+  colorField: string,
+  xScale: ScaleLinear<number, number>,
+  yScale: ScaleBand<string>,
+  bandwidth: number,
+  baseline: number,
+  scales: ResolvedScales,
+): RectMark[] {
+  const marks: RectMark[] = [];
+
+  for (const row of data) {
+    const category = String(row[categoryField] ?? '');
+    const value = Number(row[valueField] ?? 0);
+    if (!Number.isFinite(value)) continue;
+
+    const bandY = yScale(category);
+    if (bandY === undefined) continue;
+
+    const groupKey = String(row[colorField] ?? '');
+    const color = getColor(scales, groupKey);
+    const xPos = value >= 0 ? baseline : xScale(value);
+    const barWidth = Math.max(Math.abs(xScale(value) - baseline), MIN_BAR_WIDTH);
+
+    const aria: MarkAria = {
+      label: `${category}, ${groupKey}: ${formatLabelValue(value)}`,
+    };
+
+    marks.push({
+      type: 'rect',
+      x: xPos,
+      y: bandY,
+      width: barWidth,
+      height: bandwidth,
+      fill: isGradientDef(color) ? orientGradientForHorizontalBar(color) : color,
+      cornerRadius: 2,
+      data: row as Record<string, unknown>,
+      aria,
+      orient: 'horizontal',
+    });
+  }
+
+  return marks;
+}
+
+function applyMarkDefOverrides(
+  marks: RectMark[],
+  spec: NormalizedChartSpec,
+  bandwidth: number,
+): RectMark[] {
+  const { markDef } = spec;
+  const fixedSize = markDef.size;
+  const crSpec = markDef.cornerRadius;
+
+  if (fixedSize == null && crSpec == null) return marks;
+
+  // Identify the rightmost segment per stackGroup (largest `x + width`).
+  // Only that segment receives the corner rounding so the seams between
+  // stacked segments stay square and flush.
+  const rightPerStack = new Map<string, RectMark>();
+  for (const mark of marks) {
+    if (mark.stackGroup === undefined) continue;
+    const current = rightPerStack.get(mark.stackGroup);
+    const markRight = mark.x + mark.width;
+    if (!current || markRight > current.x + current.width) {
+      rightPerStack.set(mark.stackGroup, mark);
+    }
+  }
+
+  for (const mark of marks) {
+    if (fixedSize != null && mark.stackGroup === undefined) {
+      const barHeight = Math.min(fixedSize, bandwidth);
+      const offset = (bandwidth - barHeight) / 2;
+      mark.y = mark.y + offset;
+      mark.height = barHeight;
+    }
+    const effectiveHeight = mark.height;
+    const isStacked = mark.stackGroup !== undefined;
+    const isStackRight = isStacked && rightPerStack.get(mark.stackGroup!) === mark;
+
+    if (isStacked && !isStackRight) continue;
+
+    if (crSpec === 'pill') {
+      mark.cornerRadius = effectiveHeight / 2;
+    } else if (typeof crSpec === 'number') {
+      mark.cornerRadius = crSpec;
+    } else {
+      continue;
+    }
+
+    if (isStackRight) {
+      mark.cornerRadiusSides = { tl: false, tr: true, br: true, bl: false };
+    }
+  }
+  return marks;
+}
+
+/** Compute simple (non-grouped) horizontal bars. */
+function computeSimpleBars(
+  data: DataRow[],
+  valueField: string,
+  categoryField: string,
+  xScale: ScaleLinear<number, number>,
+  yScale: ScaleBand<string>,
+  bandwidth: number,
+  baseline: number,
+  scales: ResolvedScales,
+  sequentialColor = false,
+  conditionalColor?: ConditionalValueDef,
+): RectMark[] {
+  const marks: RectMark[] = [];
+
+  for (const row of data) {
+    const category = String(row[categoryField] ?? '');
+    const value = Number(row[valueField] ?? 0);
+    if (!Number.isFinite(value)) continue;
+
+    const bandY = yScale(category);
+    if (bandY === undefined) continue;
+
+    let color: string | GradientDef;
+    if (conditionalColor) {
+      const resolved = resolveConditionalValue(row, conditionalColor);
+      if (resolved != null) {
+        color = isGradientDef(resolved) ? resolved : String(resolved);
+      } else {
+        color = getColor(scales, '__default__');
+      }
+    } else if (sequentialColor) {
+      color = getSequentialColor(scales, value);
+    } else {
+      color = getColor(scales, '__default__');
+    }
+    const xPos = value >= 0 ? baseline : xScale(value);
+    const barWidth = Math.max(Math.abs(xScale(value) - baseline), MIN_BAR_WIDTH);
+
+    const aria: MarkAria = {
+      label: `${category}: ${formatLabelValue(value)}`,
+    };
+
+    marks.push({
+      type: 'rect',
+      x: xPos,
+      y: bandY,
+      width: barWidth,
+      height: bandwidth,
+      fill: isGradientDef(color) ? orientGradientForHorizontalBar(color) : color,
+      cornerRadius: 2,
+      data: row as Record<string, unknown>,
+      aria,
+      orient: 'horizontal',
+    });
+  }
+
+  return marks;
+}

package/src/charts/bar/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Bar chart module (horizontal bars).
+ *
+ * Exports the bar chart renderer and computation functions.
+ */
+
+import type { Mark } from '@opendata-ai/openchart-core';
+import { resolveFieldFormatter } from '../../format/field-format';
+import type { ChartRenderer } from '../registry';
+import { computeBarMarks } from './compute';
+import { computeBarLabels } from './labels';
+
+// ---------------------------------------------------------------------------
+// Bar chart renderer
+// ---------------------------------------------------------------------------
+
+export const barRenderer: ChartRenderer = (
+  spec,
+  scales,
+  chartArea,
+  strategy,
+  theme,
+  containerWidth,
+) => {
+  const marks = computeBarMarks(spec, scales, chartArea, strategy, containerWidth);
+
+  // Compute and attach value labels (respects spec.labels.density)
+  const valueField =
+    spec.encoding?.x && 'field' in spec.encoding.x ? spec.encoding.x.field : undefined;
+  const labelFormatter = resolveFieldFormatter({
+    surfaceFormat: spec.labels.format,
+    channelFormat:
+      spec.encoding?.x && 'format' in spec.encoding.x ? spec.encoding.x.format : undefined,
+    values: valueField ? spec.data.map((r) => r[valueField]) : [],
+  });
+  const labels = computeBarLabels(
+    marks,
+    chartArea,
+    spec.labels.density,
+    labelFormatter,
+    spec.labels.prefix,
+    valueField,
+    spec.labels.color,
+    theme.isDark,
+    spec.labels.fontSize,
+    spec.labels.suffix,
+  );
+  for (let i = 0; i < marks.length && i < labels.length; i++) {
+    marks[i].label = labels[i];
+  }
+
+  return marks as Mark[];
+};
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { computeBarMarks } from './compute';
+export { computeBarLabels } from './labels';