@cdx-ui/components 0.3.4 → 0.3.6

package/src/components/LineChart/geometry.ts

@@ -0,0 +1,957 @@
+import { niceTicks } from '../chart/ticks';
+import type { ChartAxis, ChartReferenceLine, ChartSeriesBase } from '../chart/types';
+import type { ChartColor } from '../chart/palette';
+
+/** How points connect. Names match MUI X `curve`. */
+export type LineChartCurve = 'linear' | 'monotoneX' | 'stepAfter';
+
+export interface LineChartSeries<TRow extends object> extends ChartSeriesBase<TRow> {
+  /** Series type. Optional on `LineChart`; reserved for charts that mix bars and lines. */
+  type?: 'line';
+  /**
+   * How points connect. `stepAfter` holds each value until the next point.
+   * @default 'monotoneX'
+   */
+  curve?: LineChartCurve;
+  /**
+   * Fills under the line toward zero (or the domain edge nearest it) with a fade of the
+   * series color.
+   * @default false
+   */
+  area?: boolean;
+  /**
+   * Draws a mark on each defined point. A function picks points by `index` (the `dataset` row).
+   * @default false
+   */
+  showMark?: boolean | ((params: { index: number }) => boolean);
+  /**
+   * Dashes the whole line.
+   * @default false
+   */
+  dashed?: boolean;
+  /**
+   * `dataset` row where the line switches from solid to dashed (e.g. actual → forecast). The
+   * curve still uses every point, so the join stays smooth.
+   */
+  dashedFrom?: number;
+}
+
+export interface LineChartMarker {
+  /** `dataset` row to pin to. Rows with the same category label resolve independently. */
+  dataIndex: number;
+  /** Series to pin to. Defaults to the first series with a value at `dataIndex`. */
+  seriesId?: string;
+  /** Caption above the point, e.g. "Rent". */
+  label?: string;
+  /**
+   * Draw the formatted value beside the point.
+   * @default false
+   */
+  showValue?: boolean;
+  /** Chart token for the dot. Defaults to that series' color. */
+  color?: ChartColor;
+  /** Extra legend row, e.g. "Today". */
+  legend?: string;
+  /**
+   * Vertical dashed guide through the point.
+   * @default true
+   */
+  guide?: boolean;
+  /**
+   * Filled dot on the line.
+   * @default true
+   */
+  dot?: boolean;
+}
+
+export interface LineCategory {
+  /** Axis label. */
+  readonly label: string;
+  /** Tooltip and screen reader name. */
+  readonly title: string;
+  readonly tick: boolean;
+}
+
+export interface LineSeriesInput {
+  readonly id: string;
+  readonly label: string;
+  readonly curve: LineChartCurve;
+  readonly area: boolean;
+  readonly dashed: boolean;
+  /** Row where the dash starts, or `-1`. */
+  readonly dashAt: number;
+  readonly values: readonly (number | null)[];
+}
+
+export interface LineDomainOptions {
+  readonly min?: number;
+  readonly max?: number;
+  readonly tickNumber?: number;
+}
+
+export interface LineChartGutters {
+  readonly paddingLeft: number;
+  readonly paddingRight: number;
+  readonly paddingTop: number;
+  readonly paddingBottom: number;
+}
+
+export interface LineChartMarkerLayout {
+  readonly key: string;
+  readonly index: number;
+  readonly seriesIndex: number;
+  readonly seriesId: string;
+  readonly x: number;
+  readonly y: number;
+  readonly value: number;
+  readonly label?: string;
+  readonly showValue: boolean;
+  readonly color?: ChartColor;
+  readonly legend?: string;
+  readonly guide: boolean;
+  readonly dot: boolean;
+}
+
+export interface LinePoint {
+  readonly index: number;
+  readonly value: number | null;
+  readonly x: number;
+  readonly y: number | null;
+}
+
+export interface LineSeriesLayout {
+  readonly key: string;
+  readonly label: string;
+  readonly curve: LineChartCurve;
+  readonly area: boolean;
+  readonly dashed: boolean;
+  readonly path: string;
+  readonly dashedPath: string;
+  readonly dashAt: number;
+  readonly areaPath: string;
+  readonly points: readonly LinePoint[];
+}
+
+export interface LineLabelAnchor {
+  readonly label: string;
+  readonly title: string;
+  readonly x: number;
+  readonly y: number;
+  readonly tick: boolean;
+}
+
+export interface LineValueTick {
+  readonly value: number;
+  readonly x: number;
+  readonly y: number;
+  readonly text: string;
+}
+
+export interface LineGridLine {
+  readonly x1: number;
+  readonly y1: number;
+  readonly x2: number;
+  readonly y2: number;
+}
+
+export interface LineChartLayout {
+  readonly series: readonly LineSeriesLayout[];
+  readonly categoryLabels: readonly LineLabelAnchor[];
+  readonly valueTicks: readonly LineValueTick[];
+  readonly gridLines: readonly LineGridLine[];
+  readonly referenceLines: readonly (LineGridLine & { readonly label?: string })[];
+  /** Where areas close: zero, or the domain edge nearest it. Lines rise from here on entry. */
+  readonly baselineY: number;
+  readonly plot: {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+  };
+}
+
+export const MIN_LINE_POINT_BAND = 32;
+/** Max distance from a series stroke (overlay px) that still counts as hovering the line. */
+export const LINE_POINTER_HIT_PX = 20;
+/** Extra radius around a plotted point (dots / markers) so a valley like Lowest is easy to hit. */
+export const LINE_POINT_HIT_PX = 28;
+/** Extra plot padding when a marker draws a caption or value. */
+export const LINE_MARKER_PADDING_TOP = 28;
+export const LINE_MARKER_PADDING_RIGHT = 36;
+export const DEFAULT_LINE_TICK_NUMBER = 4;
+
+const VALUE_TICK_LEFT = 40;
+const VALUE_TICK_END = 28;
+const TIGHT_GUTTER = 8;
+const PLOT_END_GUTTER = 20;
+const CATEGORY_GUTTER = 28;
+
+function round2(value: number): number {
+  'worklet';
+  const rounded = Math.round(value * 100) / 100;
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+
+function readNumber(row: object, key: string): number | null {
+  const raw = (row as Record<string, unknown>)[key];
+  if (typeof raw !== 'number' || !Number.isFinite(raw)) {
+    return null;
+  }
+  return raw;
+}
+
+function rawCategory(row: object | undefined, key: string | undefined, index: number): unknown {
+  if (key === undefined || row === undefined) {
+    return index;
+  }
+  return (row as Record<string, unknown>)[key];
+}
+
+function categoryText(
+  raw: unknown,
+  index: number,
+  location: 'tick' | 'tooltip',
+  axis: ChartAxis<object> | undefined,
+): string {
+  if (typeof raw === 'string') {
+    return raw;
+  }
+  if (typeof raw === 'number') {
+    return axis?.valueFormatter?.(raw, { location, dataIndex: index }) ?? String(raw);
+  }
+  if (raw === null || raw === undefined) {
+    return '';
+  }
+  return String(raw as string | boolean | bigint);
+}
+
+/**
+ * Maps the public `dataset` + `series` + `xAxis` props onto geometry inputs. Row keys are read
+ * only through `dataKey`, so no key is reserved.
+ */
+export function resolveLineChartData<TRow extends object>({
+  dataset,
+  series,
+  xAxis,
+}: {
+  readonly dataset: readonly TRow[];
+  readonly series: readonly LineChartSeries<TRow>[];
+  readonly xAxis?: ChartAxis<TRow>;
+}): { readonly categories: LineCategory[]; readonly series: LineSeriesInput[] } {
+  const axis = xAxis as ChartAxis<object> | undefined;
+  const interval = axis?.tickLabelInterval;
+  const hidden = axis?.position === 'none';
+  const categories = dataset.map((row, index): LineCategory => {
+    const raw = rawCategory(row, axis?.dataKey, index);
+    const label = categoryText(raw, index, 'tick', axis);
+    const shown = typeof interval === 'function' ? interval(raw, index) : true;
+    return {
+      label,
+      title: categoryText(raw, index, 'tooltip', axis),
+      tick: !hidden && shown && label.length > 0,
+    };
+  });
+  const inputs = series.map((item): LineSeriesInput => {
+    const dashed = item.dashed === true;
+    const dashAt =
+      dashed || item.dashedFrom === undefined || !Number.isInteger(item.dashedFrom)
+        ? -1
+        : item.dashedFrom;
+    return {
+      id: item.id,
+      label: item.label ?? '',
+      curve: item.curve ?? 'monotoneX',
+      area: item.area === true,
+      dashed,
+      dashAt,
+      values: dataset.map((row) => readNumber(row, item.dataKey)),
+    };
+  });
+  return { categories, series: inputs };
+}
+
+export function lineChartGutters({
+  showValueTicks = true,
+  showCategoryLabels = true,
+}: {
+  readonly showValueTicks?: boolean;
+  readonly showCategoryLabels?: boolean;
+} = {}): LineChartGutters {
+  return {
+    paddingLeft: showValueTicks ? VALUE_TICK_LEFT : TIGHT_GUTTER,
+    paddingRight: showValueTicks ? VALUE_TICK_END : PLOT_END_GUTTER,
+    paddingTop: TIGHT_GUTTER,
+    paddingBottom: showCategoryLabels ? CATEGORY_GUTTER : TIGHT_GUTTER,
+  };
+}
+
+export function resolveLineChartContentSize({
+  viewportWidth,
+  viewportHeight,
+  categoryCount,
+  gutters,
+  scrollable,
+  visiblePoints,
+}: {
+  readonly viewportWidth: number;
+  readonly viewportHeight: number;
+  readonly categoryCount: number;
+  readonly gutters: LineChartGutters;
+  readonly scrollable: boolean;
+  readonly visiblePoints?: number;
+}): { readonly width: number; readonly height: number } {
+  if (!scrollable || categoryCount <= 0) {
+    return { width: viewportWidth, height: viewportHeight };
+  }
+
+  const plotWidth = Math.max(viewportWidth - gutters.paddingLeft - gutters.paddingRight, 0);
+  const band =
+    visiblePoints !== undefined && visiblePoints > 0
+      ? plotWidth / Math.max(visiblePoints - 1, 1)
+      : MIN_LINE_POINT_BAND;
+  const contentPlot = Math.max(plotWidth, Math.max(categoryCount - 1, 1) * band);
+  return {
+    width: contentPlot + gutters.paddingLeft + gutters.paddingRight,
+    height: viewportHeight,
+  };
+}
+
+/**
+ * Value domain and ticks. `min` / `max` pin that end exactly; an open end rounds to a readable
+ * tick. `tickNumber` is approximate.
+ */
+export function lineValueDomain(
+  values: readonly number[],
+  { min: minOption, max: maxOption, tickNumber = DEFAULT_LINE_TICK_NUMBER }: LineDomainOptions = {},
+): { readonly min: number; readonly max: number; readonly ticks: readonly number[] } {
+  const min = minOption !== undefined && Number.isFinite(minOption) ? minOption : undefined;
+  const max = maxOption !== undefined && Number.isFinite(maxOption) ? maxOption : undefined;
+  let low = min ?? (values.length > 0 ? Math.min(...values) : 0);
+  let high = max ?? (values.length > 0 ? Math.max(...values) : 1);
+  if (low > high) {
+    [low, high] = [high, low];
+  }
+  if (low === high) {
+    if (min === undefined) {
+      low -= 1;
+    }
+    if (max === undefined || min !== undefined) {
+      high += 1;
+    }
+  }
+  const nice = niceTicks(low, high, tickNumber);
+  const domainMin = min ?? nice[0] ?? low;
+  const domainMax = max ?? nice[nice.length - 1] ?? high;
+  const epsilon = (domainMax - domainMin) * 1e-9;
+  const ticks = nice.filter((tick) => tick >= domainMin - epsilon && tick <= domainMax + epsilon);
+  return { min: domainMin, max: domainMax, ticks };
+}
+
+function coord(x: number, y: number): string {
+  'worklet';
+  return `${String(round2(x))} ${String(round2(y))}`;
+}
+
+function linearPath(points: readonly { x: number; y: number }[]): string {
+  'worklet';
+  return points
+    .map((point, index) => `${index === 0 ? 'M' : 'L'} ${coord(point.x, point.y)}`)
+    .join(' ');
+}
+
+function stepPath(points: readonly { x: number; y: number }[]): string {
+  'worklet';
+  if (points.length === 0) {
+    return '';
+  }
+  const parts = [`M ${coord(points[0].x, points[0].y)}`];
+  for (let index = 1; index < points.length; index += 1) {
+    const prev = points[index - 1];
+    const point = points[index];
+    parts.push(`L ${coord(point.x, prev.y)}`, `L ${coord(point.x, point.y)}`);
+  }
+  return parts.join(' ');
+}
+
+function monotoneControls(points: readonly { x: number; y: number }[]): {
+  readonly dx: number[];
+  readonly tangent: number[];
+} {
+  'worklet';
+  const count = points.length;
+  const dx: number[] = [];
+  const slope: number[] = [];
+  for (let index = 0; index < count - 1; index += 1) {
+    const deltaX = points[index + 1].x - points[index].x;
+    dx.push(deltaX);
+    slope.push(deltaX === 0 ? 0 : (points[index + 1].y - points[index].y) / deltaX);
+  }
+
+  const tangent: number[] = [slope[0]];
+  for (let index = 1; index < count - 1; index += 1) {
+    tangent.push(slope[index - 1] * slope[index] <= 0 ? 0 : (slope[index - 1] + slope[index]) / 2);
+  }
+  tangent.push(slope[count - 2]);
+
+  for (let index = 0; index < count - 1; index += 1) {
+    if (Math.abs(slope[index]) < 1e-8) {
+      tangent[index] = 0;
+      tangent[index + 1] = 0;
+      continue;
+    }
+    const alpha = tangent[index] / slope[index];
+    const beta = tangent[index + 1] / slope[index];
+    const magnitude = alpha * alpha + beta * beta;
+    if (magnitude > 9) {
+      const scale = 3 / Math.sqrt(magnitude);
+      tangent[index] = scale * alpha * slope[index];
+      tangent[index + 1] = scale * beta * slope[index];
+    }
+  }
+  return { dx, tangent };
+}
+
+function monotonePathSlice(
+  points: readonly { x: number; y: number }[],
+  from: number,
+  to: number,
+): string {
+  'worklet';
+  const count = points.length;
+  if (count === 0 || to < from || from < 0 || to > count - 1) {
+    return '';
+  }
+  if (from === to) {
+    return `M ${coord(points[from].x, points[from].y)}`;
+  }
+  if (count === 2) {
+    return linearPath(points.slice(from, to + 1));
+  }
+
+  const { dx, tangent } = monotoneControls(points);
+  const parts = [`M ${coord(points[from].x, points[from].y)}`];
+  for (let index = from; index < to; index += 1) {
+    const start = points[index];
+    const end = points[index + 1];
+    const handle = dx[index] / 3;
+    parts.push(
+      `C ${coord(start.x + handle, start.y + tangent[index] * handle)} ${coord(end.x - handle, end.y - tangent[index + 1] * handle)} ${coord(end.x, end.y)}`,
+    );
+  }
+  return parts.join(' ');
+}
+
+function monotonePath(points: readonly { x: number; y: number }[]): string {
+  'worklet';
+  if (points.length === 0) {
+    return '';
+  }
+  return monotonePathSlice(points, 0, points.length - 1);
+}
+
+function pathForCurve(points: readonly { x: number; y: number }[], curve: LineChartCurve): string {
+  'worklet';
+  if (curve === 'stepAfter') {
+    return stepPath(points);
+  }
+  if (curve === 'monotoneX') {
+    return monotonePath(points);
+  }
+  return linearPath(points);
+}
+
+function pathSlice(
+  points: readonly { x: number; y: number }[],
+  curve: LineChartCurve,
+  from: number,
+  to: number,
+): string {
+  'worklet';
+  if (to <= from) {
+    return '';
+  }
+  if (curve === 'monotoneX') {
+    return monotonePathSlice(points, from, to);
+  }
+  return pathForCurve(points.slice(from, to + 1), curve);
+}
+
+function areaFromLine(
+  linePath: string,
+  run: readonly { x: number; y: number }[],
+  baselineY: number,
+): string {
+  'worklet';
+  if (linePath.length === 0 || run.length === 0) {
+    return '';
+  }
+  const first = run[0];
+  const last = run[run.length - 1];
+  return `${linePath} L ${coord(last.x, baselineY)} L ${coord(first.x, baselineY)} Z`;
+}
+
+/**
+ * Line and area paths for one series. `ys` uses `NaN` for missing values, which
+ * open a gap. Runs on the UI thread while a chart animates.
+ * `dashAt` is a category index; cubics before it stay solid, after it dashed,
+ * using the same monotone tangents so the join stays round.
+ */
+export function lineSeriesPaths(
+  xs: readonly number[],
+  ys: readonly number[],
+  curve: LineChartCurve,
+  baselineY: number,
+  dashAt = -1,
+): { readonly path: string; readonly dashedPath: string; readonly areaPath: string } {
+  'worklet';
+  const runs: { x: number; y: number; index: number }[][] = [];
+  let current: { x: number; y: number; index: number }[] = [];
+  for (let index = 0; index < ys.length; index += 1) {
+    const y = ys[index];
+    if (!Number.isFinite(y)) {
+      if (current.length > 0) {
+        runs.push(current);
+        current = [];
+      }
+      continue;
+    }
+    current.push({ x: xs[index] ?? 0, y, index });
+  }
+  if (current.length > 0) {
+    runs.push(current);
+  }
+  const solids: string[] = [];
+  const dashes: string[] = [];
+  const areas: string[] = [];
+  for (const run of runs) {
+    const line = pathForCurve(run, curve);
+    areas.push(areaFromLine(line, run, baselineY));
+    const first = run[0]?.index ?? -1;
+    const last = run[run.length - 1]?.index ?? -1;
+    if (dashAt < 0 || dashAt <= first || dashAt >= last) {
+      if (dashAt >= 0 && dashAt <= first) {
+        dashes.push(line);
+      } else {
+        solids.push(line);
+      }
+      continue;
+    }
+    const split = run.findIndex((point) => point.index === dashAt);
+    if (split <= 0) {
+      solids.push(line);
+      continue;
+    }
+    solids.push(pathSlice(run, curve, 0, split));
+    dashes.push(pathSlice(run, curve, split, run.length - 1));
+  }
+  return {
+    path: solids.join(' '),
+    dashedPath: dashes.join(' '),
+    areaPath: areas.join(' '),
+  };
+}
+
+/** Pins each marker to its `dataIndex` row; markers that cannot resolve are dropped. */
+export function layoutLineChartMarkers(
+  markers: readonly LineChartMarker[],
+  series: readonly LineSeriesLayout[],
+): readonly LineChartMarkerLayout[] {
+  return markers.flatMap((marker, markerIndex) => {
+    const index = marker.dataIndex;
+    if (!Number.isInteger(index)) {
+      return [];
+    }
+    const seriesItem =
+      marker.seriesId !== undefined
+        ? series.find((item) => item.key === marker.seriesId)
+        : series.find((item) => item.points[index]?.y != null);
+    const point = seriesItem?.points[index];
+    if (seriesItem === undefined || point?.y == null || point.value == null) {
+      return [];
+    }
+    return [
+      {
+        key: `${seriesItem.key}-${String(index)}-${String(markerIndex)}`,
+        index,
+        seriesIndex: series.indexOf(seriesItem),
+        seriesId: seriesItem.key,
+        x: point.x,
+        y: point.y,
+        value: point.value,
+        label: marker.label,
+        showValue: marker.showValue === true,
+        color: marker.color,
+        legend: marker.legend,
+        guide: marker.guide !== false,
+        dot: marker.dot !== false,
+      },
+    ];
+  });
+}
+
+function distanceToSegment(
+  px: number,
+  py: number,
+  ax: number,
+  ay: number,
+  bx: number,
+  by: number,
+): number {
+  const dx = bx - ax;
+  const dy = by - ay;
+  const length = dx * dx + dy * dy;
+  if (length === 0) {
+    return Math.hypot(px - ax, py - ay);
+  }
+  const t = Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / length));
+  return Math.hypot(px - (ax + t * dx), py - (ay + t * dy));
+}
+
+interface StrokePoint {
+  readonly x: number;
+  readonly y: number;
+  readonly index: number;
+}
+
+function cubicPoint(
+  t: number,
+  p0: StrokePoint,
+  p1: { readonly x: number; readonly y: number },
+  p2: { readonly x: number; readonly y: number },
+  p3: StrokePoint,
+): { readonly x: number; readonly y: number } {
+  const u = 1 - t;
+  const a = u * u * u;
+  const b = 3 * u * u * t;
+  const c = 3 * u * t * t;
+  const d = t * t * t;
+  return {
+    x: a * p0.x + b * p1.x + c * p2.x + d * p3.x,
+    y: a * p0.y + b * p1.y + c * p2.y + d * p3.y,
+  };
+}
+
+function sampleMonotoneRun(points: readonly StrokePoint[]): StrokePoint[] {
+  if (points.length < 3) {
+    return [...points];
+  }
+  const count = points.length;
+  const dx: number[] = [];
+  const slope: number[] = [];
+  for (let index = 0; index < count - 1; index += 1) {
+    const from = points[index];
+    const to = points[index + 1];
+    if (from === undefined || to === undefined) {
+      continue;
+    }
+    const deltaX = to.x - from.x;
+    dx.push(deltaX);
+    slope.push(deltaX === 0 ? 0 : (to.y - from.y) / deltaX);
+  }
+  const tangent: number[] = [slope[0] ?? 0];
+  for (let index = 1; index < count - 1; index += 1) {
+    tangent.push(
+      (slope[index - 1] ?? 0) * (slope[index] ?? 0) <= 0
+        ? 0
+        : ((slope[index - 1] ?? 0) + (slope[index] ?? 0)) / 2,
+    );
+  }
+  tangent.push(slope[count - 2] ?? 0);
+  for (let index = 0; index < count - 1; index += 1) {
+    if (Math.abs(slope[index] ?? 0) < 1e-8) {
+      tangent[index] = 0;
+      tangent[index + 1] = 0;
+    }
+  }
+
+  const sampled: StrokePoint[] = [];
+  const steps = 8;
+  for (let index = 0; index < count - 1; index += 1) {
+    const start = points[index];
+    const end = points[index + 1];
+    if (start === undefined || end === undefined) {
+      continue;
+    }
+    const handle = (dx[index] ?? 0) / 3;
+    const c1 = { x: start.x + handle, y: start.y + (tangent[index] ?? 0) * handle };
+    const c2 = { x: end.x - handle, y: end.y - (tangent[index + 1] ?? 0) * handle };
+    for (let step = 0; step < steps; step += 1) {
+      const t = step / steps;
+      const point = cubicPoint(t, start, c1, c2, end);
+      sampled.push({
+        x: point.x,
+        y: point.y,
+        index: t < 0.5 ? start.index : end.index,
+      });
+    }
+  }
+  const last = points[count - 1];
+  if (last !== undefined) {
+    sampled.push(last);
+  }
+  return sampled;
+}
+
+function strokeSamples(points: readonly StrokePoint[], curve: LineChartCurve): StrokePoint[] {
+  if (curve === 'monotoneX') {
+    return sampleMonotoneRun(points);
+  }
+  if (curve === 'stepAfter') {
+    const sampled: StrokePoint[] = [];
+    for (let index = 0; index < points.length; index += 1) {
+      const from = points[index];
+      const to = points[index + 1];
+      if (from === undefined) {
+        continue;
+      }
+      sampled.push(from);
+      if (to !== undefined) {
+        sampled.push({ x: to.x, y: from.y, index: from.index });
+      }
+    }
+    return sampled;
+  }
+  return [...points];
+}
+
+/**
+ * Category index of the closest point on any series stroke, or `null` when the pointer is
+ * farther than `maxDistance` from every line. Overlay coordinates (`plot.x` already subtracted).
+ * Uses the same monotone cubics as the painted path so a valley (Lowest) still hits.
+ */
+export function nearestCategoryOnLines(
+  series: readonly LineSeriesLayout[],
+  overlayX: number,
+  overlayY: number,
+  plotOffsetX: number,
+  maxDistance: number,
+  pointDistance: number = maxDistance,
+): number | null {
+  let bestDistance = Math.max(maxDistance, pointDistance);
+  let bestIndex: number | null = null;
+
+  for (const item of series) {
+    const points: StrokePoint[] = item.points.flatMap((point) =>
+      point.y == null ? [] : [{ x: point.x - plotOffsetX, y: point.y, index: point.index }],
+    );
+    for (const point of points) {
+      const distance = Math.hypot(overlayX - point.x, overlayY - point.y);
+      if (distance <= pointDistance && distance <= bestDistance) {
+        bestDistance = distance;
+        bestIndex = point.index;
+      }
+    }
+    const sampled = strokeSamples(points, item.curve);
+    for (let i = 0; i < sampled.length; i += 1) {
+      const from = sampled[i];
+      const to = sampled[i + 1];
+      if (from === undefined) {
+        continue;
+      }
+      const distance =
+        to === undefined
+          ? Math.hypot(overlayX - from.x, overlayY - from.y)
+          : distanceToSegment(overlayX, overlayY, from.x, from.y, to.x, to.y);
+      if (distance > maxDistance || distance > bestDistance) {
+        continue;
+      }
+      bestDistance = distance;
+      if (to === undefined) {
+        bestIndex = from.index;
+      } else {
+        const closerToStart =
+          Math.hypot(overlayX - from.x, overlayY - from.y) <=
+          Math.hypot(overlayX - to.x, overlayY - to.y);
+        bestIndex = closerToStart ? from.index : to.index;
+      }
+    }
+  }
+
+  return bestIndex;
+}
+
+/**
+ * Category under the pointer when it is inside the plot box. Snaps to the nearest category on X.
+ * Overlay coordinates (`plot.x` already subtracted).
+ */
+export function nearestCategoryInPlot(
+  labels: readonly { readonly x: number }[],
+  plot: { readonly x: number; readonly y: number; readonly width: number; readonly height: number },
+  overlayX: number,
+  overlayY: number,
+  plotOffsetX: number,
+): number | null {
+  if (labels.length === 0) {
+    return null;
+  }
+  if (overlayY < plot.y || overlayY > plot.y + plot.height) {
+    return null;
+  }
+  if (overlayX < 0 || overlayX > plot.width) {
+    return null;
+  }
+  let bestIndex = 0;
+  let bestDist = Number.POSITIVE_INFINITY;
+  labels.forEach((item, index) => {
+    const dist = Math.abs(item.x - plotOffsetX - overlayX);
+    if (dist < bestDist) {
+      bestDist = dist;
+      bestIndex = index;
+    }
+  });
+  return bestIndex;
+}
+
+export function lineChartMarkerGutters(
+  categoryCount: number,
+  markers: readonly LineChartMarker[] | undefined,
+  base: LineChartGutters = lineChartGutters(),
+): LineChartGutters {
+  if (markers === undefined || markers.length === 0) {
+    return base;
+  }
+  const hasCaption = markers.some(
+    (marker) =>
+      (marker.label !== undefined && marker.label.length > 0) || marker.showValue === true,
+  );
+  const hasEndValue = markers.some(
+    (marker) => marker.showValue === true && marker.dataIndex === categoryCount - 1,
+  );
+  return {
+    ...base,
+    paddingTop: hasCaption ? LINE_MARKER_PADDING_TOP : base.paddingTop,
+    paddingRight: hasEndValue ? LINE_MARKER_PADDING_RIGHT : base.paddingRight,
+  };
+}
+
+export function layoutLineChart({
+  categories,
+  series,
+  width,
+  height,
+  referenceLines = [],
+  yAxis,
+  formatTick = String,
+  gutters: guttersProp,
+}: {
+  readonly categories: readonly LineCategory[];
+  readonly series: readonly LineSeriesInput[];
+  readonly width: number;
+  readonly height: number;
+  readonly referenceLines?: readonly ChartReferenceLine[];
+  readonly yAxis?: LineDomainOptions;
+  readonly formatTick?: (value: number) => string;
+  readonly gutters?: LineChartGutters;
+}): LineChartLayout {
+  const empty = {
+    series: [],
+    categoryLabels: [],
+    valueTicks: [],
+    gridLines: [],
+    referenceLines: [],
+    baselineY: 0,
+    plot: { x: 0, y: 0, width: 0, height: 0 },
+  };
+  if (width <= 0 || height <= 0 || categories.length === 0 || series.length === 0) {
+    return empty;
+  }
+
+  const gutters = guttersProp ?? lineChartGutters();
+  const plot = {
+    x: gutters.paddingLeft,
+    y: gutters.paddingTop,
+    width: Math.max(width - gutters.paddingLeft - gutters.paddingRight, 0),
+    height: Math.max(height - gutters.paddingTop - gutters.paddingBottom, 0),
+  };
+
+  const values = [
+    ...series.flatMap((item) => item.values.filter((value): value is number => value !== null)),
+    ...referenceLines.flatMap((line) => (Number.isFinite(line.value) ? [line.value] : [])),
+  ];
+  const domain = lineValueDomain(values, yAxis);
+  const span = domain.max - domain.min || 1;
+  const lastIndex = Math.max(categories.length - 1, 1);
+
+  const valueToY = (value: number) => plot.y + plot.height * (1 - (value - domain.min) / span);
+  const indexToX = (index: number) =>
+    categories.length === 1 ? plot.x + plot.width / 2 : plot.x + (index / lastIndex) * plot.width;
+  const baselineY = valueToY(Math.min(Math.max(0, domain.min), domain.max));
+
+  const categoryLabels: LineLabelAnchor[] = categories.map((category, index) => ({
+    label: category.label,
+    title: category.title,
+    x: round2(indexToX(index)),
+    y: round2(height - 8),
+    tick: category.tick,
+  }));
+
+  const seriesLayouts: LineSeriesLayout[] = series.map((item) => {
+    const points: LinePoint[] = categories.map((_, index) => {
+      const value = item.values[index] ?? null;
+      return {
+        index,
+        value,
+        x: round2(indexToX(index)),
+        y: value === null ? null : round2(valueToY(value)),
+      };
+    });
+    const dashAt = item.dashAt < categories.length ? item.dashAt : -1;
+    const { path, dashedPath, areaPath } = lineSeriesPaths(
+      points.map((point) => point.x),
+      points.map((point) => point.y ?? Number.NaN),
+      item.curve,
+      baselineY,
+      dashAt,
+    );
+    return {
+      key: item.id,
+      label: item.label,
+      curve: item.curve,
+      area: item.area,
+      dashed: item.dashed,
+      path,
+      dashedPath,
+      dashAt,
+      areaPath,
+      points,
+    };
+  });
+
+  const valueTicks: LineValueTick[] = domain.ticks.map((value) => ({
+    value,
+    x: round2(plot.x - 8),
+    y: round2(valueToY(value)),
+    text: formatTick(value),
+  }));
+
+  const gridLines: LineGridLine[] = domain.ticks.map((value) => {
+    const y = round2(valueToY(value));
+    return { x1: round2(plot.x), y1: y, x2: round2(plot.x + plot.width), y2: y };
+  });
+
+  const laidReference = referenceLines.flatMap((line) => {
+    if (!Number.isFinite(line.value)) {
+      return [];
+    }
+    const y = round2(valueToY(line.value));
+    return [
+      {
+        x1: round2(plot.x),
+        y1: y,
+        x2: round2(plot.x + plot.width),
+        y2: y,
+        label: line.label,
+      },
+    ];
+  });
+
+  return {
+    series: seriesLayouts,
+    categoryLabels,
+    valueTicks,
+    gridLines,
+    referenceLines: laidReference,
+    baselineY: round2(baselineY),
+    plot,
+  };
+}