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

package/src/layout/facet.ts

@@ -0,0 +1,91 @@
+import type { Rect } from '@opendata-ai/openchart-core';
+
+const MIN_PANEL_WIDTH = 200;
+export const MIN_PANEL_HEIGHT = 100;
+const PANEL_GAP = 12;
+const HEADER_HEIGHT = 20;
+const X_AXIS_HEIGHT = 24;
+
+export interface FacetGridPanel {
+  key: string;
+  area: Rect;
+  headerPos: { x: number; y: number };
+  row: number;
+  col: number;
+}
+
+export interface FacetGridResult {
+  panels: FacetGridPanel[];
+  columns: number;
+  rows: number;
+}
+
+export function autoColumns(panelCount: number, availableWidth: number): number {
+  const sqrtCols = Math.ceil(Math.sqrt(panelCount));
+  const fitCols = Math.max(1, Math.floor(availableWidth / MIN_PANEL_WIDTH));
+  return Math.min(sqrtCols, fitCols, panelCount);
+}
+
+export function facetMinHeight(panelCount: number, columns: number): number {
+  const rows = Math.ceil(panelCount / columns);
+  return rows * (MIN_PANEL_HEIGHT + HEADER_HEIGHT + X_AXIS_HEIGHT) + (rows - 1) * PANEL_GAP;
+}
+
+export function computeFacetGrid(
+  facetValues: string[],
+  requestedColumns: number | undefined,
+  totalArea: Rect,
+  outerAxisReservation: { left: number; bottom: number },
+): FacetGridResult {
+  const n = facetValues.length;
+  if (n === 0) return { panels: [], columns: 0, rows: 0 };
+
+  const usableWidth = totalArea.width - outerAxisReservation.left;
+  let columns = Math.min(requestedColumns ?? autoColumns(n, usableWidth), n);
+
+  // Responsive degradation: reduce columns until panels are wide enough
+  while (columns > 1) {
+    const panelWidth = (usableWidth - (columns - 1) * PANEL_GAP) / columns;
+    if (panelWidth >= MIN_PANEL_WIDTH) break;
+    columns--;
+  }
+
+  const rows = Math.ceil(n / columns);
+  const panelWidth = Math.max(0, (usableWidth - (columns - 1) * PANEL_GAP) / columns);
+  // Every row includes its own x-axis labels, so the bottom reservation
+  // applies per-row (as overhead), not just at the grid bottom.
+  const xAxisPerRow = outerAxisReservation.bottom;
+  const usableHeight = totalArea.height;
+  const panelHeight = Math.max(
+    0,
+    (usableHeight - rows * (HEADER_HEIGHT + xAxisPerRow) - (rows - 1) * PANEL_GAP) / rows,
+  );
+
+  const rowStride = HEADER_HEIGHT + panelHeight + xAxisPerRow + PANEL_GAP;
+  const panels: FacetGridPanel[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const col = i % columns;
+    const row = Math.floor(i / columns);
+    const x = totalArea.x + outerAxisReservation.left + col * (panelWidth + PANEL_GAP);
+    const y = totalArea.y + row * rowStride;
+
+    panels.push({
+      key: facetValues[i],
+      area: {
+        x,
+        y: y + HEADER_HEIGHT,
+        width: panelWidth,
+        height: panelHeight,
+      },
+      headerPos: {
+        x: x + panelWidth / 2,
+        y: y + HEADER_HEIGHT * 0.6,
+      },
+      row,
+      col,
+    });
+  }
+
+  return { panels, columns, rows };
+}

package/src/layout/gridlines.ts

@@ -0,0 +1,84 @@
+/**
+ * Gridline computation.
+ *
+ * Produces horizontal gridlines at y-axis tick positions and optional
+ * vertical gridlines at x-axis tick positions.
+ */
+
+import type { Rect } from '@opendata-ai/openchart-core';
+import type { AxesResult } from './axes';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A single gridline with start/end positions. */
+export interface GridlineSpec {
+  /** Start x. */
+  x1: number;
+  /** Start y. */
+  y1: number;
+  /** End x. */
+  x2: number;
+  /** End y. */
+  y2: number;
+  /** Whether this is a major gridline. */
+  major: boolean;
+}
+
+/** Complete gridline layout. */
+export interface GridlineLayout {
+  horizontal: GridlineSpec[];
+  vertical: GridlineSpec[];
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute gridlines from axis layouts.
+ *
+ * Horizontal gridlines span the chart width at y-axis tick positions.
+ * Vertical gridlines span the chart height at x-axis tick positions.
+ *
+ * @param axes - Computed axis layouts.
+ * @param chartArea - The chart drawing area.
+ * @param showVertical - Whether to include vertical gridlines (default: false).
+ */
+export function computeGridlines(
+  axes: AxesResult,
+  chartArea: Rect,
+  showVertical = false,
+): GridlineLayout {
+  const horizontal: GridlineSpec[] = [];
+  const vertical: GridlineSpec[] = [];
+
+  // Horizontal gridlines at y-axis ticks
+  if (axes.y) {
+    for (const gridline of axes.y.gridlines) {
+      horizontal.push({
+        x1: chartArea.x,
+        y1: gridline.position,
+        x2: chartArea.x + chartArea.width,
+        y2: gridline.position,
+        major: gridline.major,
+      });
+    }
+  }
+
+  // Vertical gridlines at x-axis ticks (off by default)
+  if (showVertical && axes.x) {
+    for (const gridline of axes.x.gridlines) {
+      vertical.push({
+        x1: gridline.position,
+        y1: chartArea.y,
+        x2: gridline.position,
+        y2: chartArea.y + chartArea.height,
+        major: gridline.major,
+      });
+    }
+  }
+
+  return { horizontal, vertical };
+}

package/src/layout/metrics.ts

@@ -0,0 +1,132 @@
+/**
+ * Metric bar layout: a row of KPI cells rendered above the chart area.
+ *
+ * Cells lay out evenly across the chart width. The bar is auto-stripped when
+ * the container is too narrow, when the chart area would be left too short,
+ * or when value text would overflow its allotted cell width. Sparkline mode
+ * never reserves space for metrics.
+ */
+import type {
+  MeasureTextFn,
+  Metric,
+  ResolvedMetricBar,
+  ResolvedMetricCell,
+} from '@opendata-ai/openchart-core';
+import { estimateTextWidth } from '@opendata-ai/openchart-core';
+
+// Font sizes default to the editorial KPI mock (10px uppercase label above a
+// 22px primary value) but are theme-driven so charts can scale the row. The
+// label/value sizes flow in from `theme.fonts.sizes.metricLabel/metricValue`.
+const DEFAULT_LABEL_FONT_SIZE = 10;
+const DEFAULT_VALUE_FONT_SIZE = 22;
+const LABEL_LINE_HEIGHT_RATIO = 1.4;
+const VALUE_LINE_HEIGHT_RATIO = 1.15;
+const INTER_ROW_GAP = 4;
+// Breathing room above labels (separates metric row from the subtitle).
+const TOP_GAP = 16;
+// Breathing room below values (separates metric row from legend / chart top).
+const BOTTOM_GAP = 20;
+
+/** Font sizes the metric layout reserves space for. */
+export interface MetricFontSizes {
+  /** Uppercase label size (px). */
+  label: number;
+  /** Primary value size (px). */
+  value: number;
+}
+
+const DEFAULT_METRIC_FONT_SIZES: MetricFontSizes = {
+  label: DEFAULT_LABEL_FONT_SIZE,
+  value: DEFAULT_VALUE_FONT_SIZE,
+};
+
+/** Minimum container width that can fit a metric bar. */
+const MIN_BAR_WIDTH = 480;
+/** Minimum chart-area height after metric reservation. */
+const MIN_CHART_HEIGHT = 150;
+/** Inner cell gutter so adjacent cells don't visually touch. */
+const CELL_INNER_PAD = 8;
+
+/**
+ * Total height the metric bar reserves above the chart area. Derived from the
+ * font sizes (theme-driven) plus the fixed gaps; never hardcoded at the call site.
+ */
+export function metricBarHeight(fonts: MetricFontSizes = DEFAULT_METRIC_FONT_SIZES): number {
+  const labelLine = fonts.label * LABEL_LINE_HEIGHT_RATIO;
+  const valueLine = fonts.value * VALUE_LINE_HEIGHT_RATIO;
+  return TOP_GAP + labelLine + INTER_ROW_GAP + valueLine + BOTTOM_GAP;
+}
+
+/**
+ * Concatenate the visible value text used for overflow detection. Joined with
+ * single spaces because the renderer separates the spans with `dx` attributes
+ * that consume roughly a space's worth of width.
+ */
+function valueRunText(metric: Metric): string {
+  const parts = [metric.value];
+  if (metric.delta) parts.push(metric.delta);
+  if (metric.secondary) parts.push(metric.secondary);
+  return parts.join(' ');
+}
+
+/**
+ * Compute the metric bar layout. Returns `undefined` when the bar should be
+ * stripped (too narrow, chart too short, or any cell would overflow).
+ */
+export function computeMetricBar(
+  metrics: Metric[] | undefined,
+  metricsTopY: number,
+  metricsArea: { x: number; width: number },
+  remainingChartHeight: number,
+  measureText?: MeasureTextFn,
+  fonts: MetricFontSizes = DEFAULT_METRIC_FONT_SIZES,
+): ResolvedMetricBar | undefined {
+  if (!metrics || metrics.length === 0) return undefined;
+  if (metricsArea.width < MIN_BAR_WIDTH) return undefined;
+  if (remainingChartHeight < MIN_CHART_HEIGHT) return undefined;
+
+  const cellWidth = metricsArea.width / metrics.length;
+
+  // Bail if any cell's value run can't fit. Half-rendered metric rows look
+  // worse than no row at all on small viewports.
+  for (const metric of metrics) {
+    const text = valueRunText(metric);
+    const measured = measureText
+      ? measureText(text, fonts.value, 510).width
+      : estimateTextWidth(text, fonts.value, 510);
+    if (measured > cellWidth - CELL_INNER_PAD) return undefined;
+  }
+
+  const labelLine = fonts.label * LABEL_LINE_HEIGHT_RATIO;
+  const labelY = metricsTopY + TOP_GAP + fonts.label; // baseline for uppercase label
+  const valueY = metricsTopY + TOP_GAP + labelLine + INTER_ROW_GAP + fonts.value;
+
+  const cells: ResolvedMetricCell[] = metrics.map((metric, i) => ({
+    x: metricsArea.x + i * cellWidth,
+    cellWidth,
+    labelY,
+    valueY,
+    metric,
+    overflowed: false,
+  }));
+
+  return {
+    y: metricsTopY,
+    height: metricBarHeight(fonts),
+    cells,
+  };
+}
+
+// Exposed for tests and consumers needing the same constants.
+export const METRIC_BAR_INTERNALS = {
+  DEFAULT_LABEL_FONT_SIZE,
+  DEFAULT_VALUE_FONT_SIZE,
+  LABEL_LINE_HEIGHT_RATIO,
+  VALUE_LINE_HEIGHT_RATIO,
+  INTER_ROW_GAP,
+  TOP_GAP,
+  BOTTOM_GAP,
+  MIN_BAR_WIDTH,
+  MIN_CHART_HEIGHT,
+  CELL_INNER_PAD,
+};