@cdx-ui/components 0.3.4 → 0.3.6

package/src/components/BarChart/geometry.ts

@@ -0,0 +1,1469 @@
+import { niceTicks } from '../chart/ticks';
+
+export type BarChartOrientation = 'vertical' | 'horizontal';
+/**
+ * Where category names sit around the plot. `top` / `bottom` apply to vertical
+ * bars; `left` / `right` apply to horizontal bars. Other combinations fall back
+ * to `bottom` or `left`. `none` draws no category names.
+ */
+export type BarChartCategoryLabelPosition = 'top' | 'bottom' | 'left' | 'right' | 'none';
+
+/**
+ * How a stack group piles its series. `diverging` stacks positive values up and negative values
+ * down from zero. `none` adds every value to one running total. `expand` scales each category to
+ * the same length, so segments show their share.
+ */
+export type BarStackOffset = 'diverging' | 'none' | 'expand';
+
+/** How the chart draws its series: side by side or stacked, a comparison overlay, or a waterfall. */
+export type BarChartKind = 'bars' | 'overlay' | 'waterfall';
+
+export type BarWaterfallRole = 'total' | 'increase' | 'decrease';
+
+/** A series resolved for layout. `id` is the public series id. */
+export interface BarGeometrySeries {
+  readonly id: string;
+  readonly dataKey: string;
+  readonly label: string;
+  /** Stack group id. Series with the same id share one bar per category. */
+  readonly stack?: string;
+  readonly stackOffset?: BarStackOffset;
+}
+
+export interface BarChartReferenceLine {
+  readonly value: number;
+  readonly label?: string;
+}
+
+export interface BarValueAxisConfig {
+  readonly min?: number;
+  readonly max?: number;
+  readonly tickNumber?: number;
+}
+
+export interface BarRect {
+  /** Row in the dataset. */
+  readonly index: number;
+  readonly seriesId: string;
+  /** Position in the resolved series list (or the category, for waterfall). Picks the fill. */
+  readonly seriesIndex: number;
+  readonly label: string;
+  readonly seriesLabel: string;
+  readonly value: number;
+  readonly plotValue: number;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  /** Round the end away from the baseline (the outer cap). */
+  readonly rounded: boolean;
+  /** Round every corner (floating waterfall steps and inner stacked segments with a gap). */
+  readonly roundAll?: boolean;
+  /** Set on stacked segments. */
+  readonly stackId?: string;
+  /** Set on `expand` segments: `plotValue` is a 0–100 share. */
+  readonly expand?: boolean;
+  /** Set on waterfall bars. */
+  readonly waterfallRole?: BarWaterfallRole;
+}
+
+export interface BarLabelAnchor {
+  readonly label: string;
+  readonly x: number;
+  readonly y: number;
+  readonly textAnchor: 'start' | 'middle' | 'end';
+}
+
+export interface BarValueTick {
+  readonly value: number;
+  readonly x: number;
+  readonly y: number;
+  readonly text: string;
+}
+
+export interface BarGridLine {
+  readonly x1: number;
+  readonly y1: number;
+  readonly x2: number;
+  readonly y2: number;
+}
+
+export interface BarReferenceLineLayout extends BarGridLine {
+  readonly label?: string;
+}
+
+export interface BarChartLayout {
+  readonly bars: BarRect[];
+  readonly categoryLabels: BarLabelAnchor[];
+  readonly valueTicks: BarValueTick[];
+  readonly gridLines: BarGridLine[];
+  readonly referenceLines: readonly BarReferenceLineLayout[];
+  /** Dashed bridges from one waterfall step to the next, at the running total. */
+  readonly connectors: readonly BarGridLine[];
+  /** Value-axis coordinate of zero (y when vertical, x when horizontal). Bars grow from here. */
+  readonly baseline: number;
+  readonly plot: {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+  };
+}
+
+/** Share of each category slot left empty around the bars. MUI X `categoryGapRatio`. */
+export const CATEGORY_GAP_RATIO = 0.36;
+/** Gap between bars in one category, as a share of one bar's thickness. MUI X `barGapRatio`. */
+export const BAR_GAP_RATIO = 0.5;
+/** Primary bar share of the overlay slot. Comparison series are thinner and peek out. */
+export const OVERLAY_PRIMARY_RATIO = 0.7;
+export const OVERLAY_COMPARE_RATIO = 0.16;
+export const OVERLAY_SPACING_RATIO = 0.08;
+/** Pixel gap between stacked segments. `0` joins them with only the outer cap rounded. */
+export const DEFAULT_STACK_GAP = 3;
+export const DEFAULT_TICK_COUNT = 4;
+/** Minimum pixels per category when scrolling. Keeps labels and bars readable. */
+export const MIN_CATEGORY_BAND = 48;
+/** `expand` ticks when the value axis sets no `min`, `max`, or `tickNumber`. */
+const EXPAND_TICKS: readonly number[] = [0, 25, 50, 75, 100];
+
+export interface BarChartGutters {
+  readonly paddingLeft: number;
+  readonly paddingRight: number;
+  readonly paddingTop: number;
+  readonly paddingBottom: number;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function round2(value: number): number {
+  const rounded = Math.round(value * 100) / 100;
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+
+/** Reads a finite number from `row[key]`. Anything else is a missing value. */
+export function readBarValue(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 readBarFlag(row: object, key: string | undefined): boolean {
+  return key !== undefined && (row as Record<string, unknown>)[key] === true;
+}
+
+interface BarGroupMember {
+  readonly item: BarGeometrySeries;
+  readonly seriesIndex: number;
+}
+
+export interface BarGroup {
+  /** `undefined` for a series drawn on its own (not stacked). */
+  readonly stackId: string | undefined;
+  readonly offset: BarStackOffset | null;
+  readonly members: readonly BarGroupMember[];
+}
+
+/**
+ * One slot per stack group, in first-appearance order. A series without `stack` gets its own
+ * slot. The first `stackOffset` set in a group applies to the whole group.
+ */
+export function resolveBarGroups(series: readonly BarGeometrySeries[]): readonly BarGroup[] {
+  const groups: {
+    stackId: string | undefined;
+    offset: BarStackOffset | null;
+    members: BarGroupMember[];
+  }[] = [];
+  const byStack = new Map<string, (typeof groups)[number]>();
+  series.forEach((item, seriesIndex) => {
+    if (item.stack === undefined) {
+      groups.push({ stackId: undefined, offset: null, members: [{ item, seriesIndex }] });
+      return;
+    }
+    let group = byStack.get(item.stack);
+    if (group === undefined) {
+      group = { stackId: item.stack, offset: null, members: [] };
+      byStack.set(item.stack, group);
+      groups.push(group);
+    }
+    group.members.push({ item, seriesIndex });
+    if (group.offset === null && item.stackOffset !== undefined) {
+      group.offset = item.stackOffset;
+    }
+  });
+  return groups.map((group) =>
+    group.stackId === undefined ? group : { ...group, offset: group.offset ?? 'diverging' },
+  );
+}
+
+function groupDomainValues(dataset: readonly object[], group: BarGroup): number[] {
+  if (group.offset === 'expand') {
+    return [0, 100];
+  }
+  const values: number[] = [];
+  for (const row of dataset) {
+    if (group.offset === null) {
+      for (const { item } of group.members) {
+        const value = readBarValue(row, item.dataKey);
+        if (value !== null) {
+          values.push(value);
+        }
+      }
+      continue;
+    }
+    let positive = 0;
+    let negative = 0;
+    let running = 0;
+    for (const { item } of group.members) {
+      const value = readBarValue(row, item.dataKey);
+      if (value === null) {
+        continue;
+      }
+      if (group.offset === 'none') {
+        running += value;
+        values.push(running);
+      } else if (value >= 0) {
+        positive += value;
+      } else {
+        negative += value;
+      }
+    }
+    if (group.offset === 'diverging') {
+      values.push(positive, negative);
+    }
+  }
+  return values;
+}
+
+function collectWaterfallTotals(
+  dataset: readonly object[],
+  dataKey: string,
+  totalKey: string | undefined,
+): number[] {
+  let cursor = 0;
+  const totals: number[] = [0];
+  dataset.forEach((row, index) => {
+    const raw = readBarValue(row, dataKey);
+    if (readBarFlag(row, totalKey)) {
+      if (raw !== null && index === 0) {
+        cursor = raw;
+      }
+      totals.push(cursor);
+      return;
+    }
+    if (raw === null) {
+      return;
+    }
+    cursor += raw;
+    totals.push(cursor);
+  });
+  return totals;
+}
+
+interface StackSegment {
+  readonly item: BarGeometrySeries;
+  readonly seriesIndex: number;
+  readonly value: number;
+  readonly display: number;
+}
+
+function stackSegments(
+  row: object,
+  members: readonly BarGroupMember[],
+  offset: BarStackOffset,
+): StackSegment[] {
+  const raw: StackSegment[] = [];
+  let positiveTotal = 0;
+  for (const { item, seriesIndex } of members) {
+    const value = readBarValue(row, item.dataKey);
+    if (value === null) {
+      continue;
+    }
+    if (offset === 'expand' && value <= 0) {
+      continue;
+    }
+    if (value > 0) {
+      positiveTotal += value;
+    }
+    raw.push({ item, seriesIndex, value, display: value });
+  }
+
+  if (offset !== 'expand' || positiveTotal <= 0) {
+    return raw;
+  }
+
+  return raw.map((segment) => ({
+    ...segment,
+    display: (segment.value / positiveTotal) * 100,
+  }));
+}
+
+function computeDomain(values: readonly number[]): { min: number; max: number } {
+  if (values.length === 0) {
+    return { min: 0, max: 1 };
+  }
+  const min = Math.min(0, ...values);
+  let max = Math.max(0, ...values);
+  if (min === max) {
+    max = 1;
+  }
+  return { min, max };
+}
+
+function finite(value: number | undefined): number | undefined {
+  return value !== undefined && Number.isFinite(value) ? value : undefined;
+}
+
+/**
+ * Value-axis domain and ticks. `min` / `max` pin the domain exactly; otherwise it rounds out to
+ * readable ticks. On an `expand` axis, `min` / `max` are 0–1 shares.
+ */
+export function resolveBarValueScale(
+  values: readonly number[],
+  axis: BarValueAxisConfig | undefined,
+  expand: boolean,
+): { readonly min: number; readonly max: number; readonly ticks: readonly number[] } {
+  const scale = expand ? 100 : 1;
+  const axisMin = finite(axis?.min);
+  const axisMax = finite(axis?.max);
+  const tickNumber = finite(axis?.tickNumber);
+  const raw = expand ? { min: 0, max: 100 } : computeDomain(values);
+  const lo = axisMin !== undefined ? axisMin * scale : raw.min;
+  let hi = axisMax !== undefined ? axisMax * scale : raw.max;
+  if (hi <= lo) {
+    hi = lo + 1;
+  }
+  const candidates =
+    expand && axisMin === undefined && axisMax === undefined && tickNumber === undefined
+      ? EXPAND_TICKS
+      : niceTicks(
+          lo,
+          hi,
+          Math.round(tickNumber ?? (expand ? EXPAND_TICKS.length : DEFAULT_TICK_COUNT)),
+        );
+  const min = axisMin !== undefined ? lo : Math.min(lo, candidates[0] ?? lo);
+  const max = axisMax !== undefined ? hi : Math.max(hi, candidates.at(-1) ?? hi);
+  const epsilon = (max - min) * 1e-9;
+  const ticks = candidates.filter((tick) => tick >= min - epsilon && tick <= max + epsilon);
+  return { min, max, ticks };
+}
+
+/** Default tick formatter when the chart passes no `formatTick`. */
+export function formatBarValue(value: number): string {
+  if (Number.isInteger(value)) {
+    return String(value);
+  }
+  return String(round2(value));
+}
+
+function categoryLabelPadding(
+  categories: readonly string[],
+  orientation: BarChartOrientation,
+): number {
+  if (orientation !== 'horizontal') {
+    return 40;
+  }
+  const longest = categories.reduce((max, label) => Math.max(max, label.length), 0);
+  return clamp(longest * 8 + 16, 64, 168);
+}
+
+const CATEGORY_EDGE_GUTTER = 28;
+/** Average `text-xs` glyph width; SVG text cannot be measured before layout. */
+const CATEGORY_LABEL_CHAR_WIDTH = 6.5;
+const VALUE_TICK_LEFT = 40;
+const VALUE_TICK_END = 28;
+const TIGHT_GUTTER = 8;
+const VALUES_END_GUTTER = 72;
+const OVERLAY_VALUES_END_GUTTER = 156;
+/** Room for `$1,234` above the tallest bar (`fontSize` 10 + iOS baseline). */
+const VALUES_TOP_GUTTER = 36;
+const PLOT_END_GUTTER = 20;
+const NEGATIVE_VALUES_GUTTER = 16;
+
+export function resolveCategoryLabelPosition(
+  orientation: BarChartOrientation,
+  position: BarChartCategoryLabelPosition | undefined,
+): BarChartCategoryLabelPosition {
+  if (position === 'none') {
+    return 'none';
+  }
+  if (orientation === 'vertical') {
+    return position === 'top' ? 'top' : 'bottom';
+  }
+  return position === 'right' ? 'right' : 'left';
+}
+
+export function resolveBarChartGutters({
+  categories,
+  hasNegative,
+  orientation,
+  barLabel,
+  categoryLabelPosition,
+  showTicks = true,
+  overlay = false,
+}: {
+  readonly categories: readonly string[];
+  readonly hasNegative: boolean;
+  readonly orientation: BarChartOrientation;
+  readonly barLabel: boolean;
+  readonly categoryLabelPosition?: BarChartCategoryLabelPosition;
+  readonly showTicks?: boolean;
+  readonly overlay?: boolean;
+}): BarChartGutters {
+  const labels = resolveCategoryLabelPosition(orientation, categoryLabelPosition);
+  if (orientation === 'vertical') {
+    const labelsTop = labels === 'top';
+    return {
+      paddingLeft: showTicks ? VALUE_TICK_LEFT : TIGHT_GUTTER,
+      paddingRight: showTicks ? VALUE_TICK_END : PLOT_END_GUTTER,
+      paddingTop: labelsTop ? CATEGORY_EDGE_GUTTER : barLabel ? VALUES_TOP_GUTTER : TIGHT_GUTTER,
+      paddingBottom:
+        (labelsTop || labels === 'none' ? TIGHT_GUTTER : CATEGORY_EDGE_GUTTER) +
+        (hasNegative && barLabel ? NEGATIVE_VALUES_GUTTER : 0),
+    };
+  }
+  const labelsRight = labels === 'right';
+  const categoryPad =
+    labels === 'none' ? TIGHT_GUTTER : categoryLabelPadding(categories, orientation);
+  const valuesEnd =
+    barLabel && overlay ? OVERLAY_VALUES_END_GUTTER : barLabel ? VALUES_END_GUTTER : TIGHT_GUTTER;
+  return {
+    paddingLeft: labelsRight ? TIGHT_GUTTER : categoryPad,
+    paddingRight: labelsRight ? categoryPad : Math.max(valuesEnd, showTicks ? VALUE_TICK_END : 0),
+    paddingTop: TIGHT_GUTTER,
+    paddingBottom: showTicks ? CATEGORY_EDGE_GUTTER : TIGHT_GUTTER,
+  };
+}
+
+/**
+ * Gutters from rows with a string `label` field. `LineChart` lays out with the same gutters.
+ */
+export function barChartGutters(
+  data: readonly object[],
+  orientation: BarChartOrientation,
+  barLabel: boolean,
+  categoryLabelPosition?: BarChartCategoryLabelPosition,
+  showTicks = true,
+  overlay = false,
+): BarChartGutters {
+  return resolveBarChartGutters({
+    categories: data.map((row) => {
+      const label = (row as Record<string, unknown>).label;
+      return typeof label === 'string' ? label : '';
+    }),
+    hasNegative: data.some((row) =>
+      Object.values(row).some((value) => typeof value === 'number' && value < 0),
+    ),
+    orientation,
+    barLabel,
+    categoryLabelPosition,
+    showTicks,
+    overlay,
+  });
+}
+
+/**
+ * Viewport is the visible box (screen or parent). Content grows when there are
+ * too many categories to keep a readable band (`scrollable` / `visiblePoints`).
+ */
+export function resolveBarChartContentSize({
+  viewportWidth,
+  viewportHeight,
+  categoryCount,
+  orientation,
+  gutters,
+  scrollable,
+  visiblePoints,
+}: {
+  readonly viewportWidth: number;
+  readonly viewportHeight: number;
+  readonly categoryCount: number;
+  readonly orientation: BarChartOrientation;
+  readonly gutters: BarChartGutters;
+  readonly scrollable: boolean;
+  readonly visiblePoints?: number;
+}): { readonly width: number; readonly height: number } {
+  if (!scrollable || categoryCount <= 0) {
+    return { width: viewportWidth, height: viewportHeight };
+  }
+
+  if (orientation === 'vertical') {
+    const plotWidth = Math.max(viewportWidth - gutters.paddingLeft - gutters.paddingRight, 0);
+    const band =
+      visiblePoints !== undefined && visiblePoints > 0
+        ? plotWidth / visiblePoints
+        : MIN_CATEGORY_BAND;
+    const contentPlot = Math.max(plotWidth, categoryCount * band);
+    return {
+      width: contentPlot + gutters.paddingLeft + gutters.paddingRight,
+      height: viewportHeight,
+    };
+  }
+
+  const plotHeight = Math.max(viewportHeight - gutters.paddingTop - gutters.paddingBottom, 0);
+  const band =
+    visiblePoints !== undefined && visiblePoints > 0
+      ? plotHeight / visiblePoints
+      : MIN_CATEGORY_BAND;
+  const contentPlot = Math.max(plotHeight, categoryCount * band);
+  return {
+    width: viewportWidth,
+    height: contentPlot + gutters.paddingTop + gutters.paddingBottom,
+  };
+}
+
+function groupedRect({
+  index,
+  seriesIndex,
+  slot,
+  item,
+  label,
+  value,
+  orientation,
+  band,
+  groupOffset,
+  thickness,
+  gap,
+  plotX,
+  plotY,
+  valueToX,
+  valueToY,
+}: {
+  readonly index: number;
+  readonly seriesIndex: number;
+  readonly slot: number;
+  readonly item: BarGeometrySeries;
+  readonly label: string;
+  readonly value: number;
+  readonly orientation: BarChartOrientation;
+  readonly band: number;
+  readonly groupOffset: number;
+  readonly thickness: number;
+  readonly gap: number;
+  readonly plotX: number;
+  readonly plotY: number;
+  readonly valueToX: (value: number) => number;
+  readonly valueToY: (value: number) => number;
+}): BarRect {
+  const zeroY = valueToY(0);
+  const zeroX = valueToX(0);
+  const base = {
+    index,
+    seriesId: item.id,
+    seriesIndex,
+    label,
+    seriesLabel: item.label,
+    value,
+    plotValue: value,
+    rounded: true,
+  };
+  if (orientation === 'vertical') {
+    const x = plotX + index * band + groupOffset + slot * (thickness + gap);
+    const y = value >= 0 ? valueToY(value) : zeroY;
+    const barHeight = Math.abs(valueToY(value) - zeroY);
+    return {
+      ...base,
+      x: round2(x),
+      y: round2(y),
+      width: round2(Math.max(thickness, 0)),
+      height: round2(Math.max(barHeight, 0)),
+    };
+  }
+
+  const y = plotY + index * band + groupOffset + slot * (thickness + gap);
+  const x = value >= 0 ? zeroX : valueToX(value);
+  const barWidth = Math.abs(valueToX(value) - zeroX);
+  return {
+    ...base,
+    x: round2(x),
+    y: round2(y),
+    width: round2(Math.max(barWidth, 0)),
+    height: round2(Math.max(thickness, 0)),
+  };
+}
+
+function overlayRect({
+  index,
+  seriesIndex,
+  item,
+  label,
+  value,
+  orientation,
+  band,
+  groupOffset,
+  inner,
+  plotX,
+  plotY,
+  valueToX,
+  valueToY,
+}: {
+  readonly index: number;
+  readonly seriesIndex: number;
+  readonly item: BarGeometrySeries;
+  readonly label: string;
+  readonly value: number;
+  readonly orientation: BarChartOrientation;
+  readonly band: number;
+  readonly groupOffset: number;
+  readonly inner: number;
+  readonly plotX: number;
+  readonly plotY: number;
+  readonly valueToX: (value: number) => number;
+  readonly valueToY: (value: number) => number;
+}): BarRect {
+  const isPrimary = seriesIndex === 0;
+  const primaryThickness = inner * OVERLAY_PRIMARY_RATIO;
+  const thickness = isPrimary ? primaryThickness : inner * OVERLAY_COMPARE_RATIO;
+  const slot = plotX + index * band + groupOffset;
+  const slotY = plotY + index * band + groupOffset;
+  const offset = isPrimary ? 0 : primaryThickness + inner * OVERLAY_SPACING_RATIO;
+  const zeroY = valueToY(0);
+  const zeroX = valueToX(0);
+  const base = {
+    index,
+    seriesId: item.id,
+    seriesIndex,
+    label,
+    seriesLabel: item.label,
+    value,
+    plotValue: value,
+    rounded: true,
+  };
+
+  if (orientation === 'vertical') {
+    const x = slot + offset;
+    const y = value >= 0 ? valueToY(value) : zeroY;
+    const barHeight = Math.abs(valueToY(value) - zeroY);
+    return {
+      ...base,
+      x: round2(x),
+      y: round2(y),
+      width: round2(Math.max(thickness, 0)),
+      height: round2(Math.max(barHeight, 0)),
+    };
+  }
+
+  const y = slotY + offset;
+  const x = value >= 0 ? zeroX : valueToX(value);
+  const barWidth = Math.abs(valueToX(value) - zeroX);
+  return {
+    ...base,
+    x: round2(x),
+    y: round2(y),
+    width: round2(Math.max(barWidth, 0)),
+    height: round2(Math.max(thickness, 0)),
+  };
+}
+
+function layoutStackedRow({
+  row,
+  label,
+  index,
+  group,
+  orientation,
+  band,
+  groupOffset,
+  thickness,
+  plotX,
+  plotY,
+  valueToX,
+  valueToY,
+  bars,
+  stackGap,
+}: {
+  readonly row: object;
+  readonly label: string;
+  readonly index: number;
+  readonly group: BarGroup;
+  readonly orientation: BarChartOrientation;
+  readonly band: number;
+  readonly groupOffset: number;
+  readonly thickness: number;
+  readonly plotX: number;
+  readonly plotY: number;
+  readonly valueToX: (value: number) => number;
+  readonly valueToY: (value: number) => number;
+  readonly bars: BarRect[];
+  readonly stackGap: number;
+}): void {
+  const offset = group.offset ?? 'diverging';
+  const shared = offset === 'none';
+  const segments = stackSegments(row, group.members, offset);
+  const lastPositiveId = shared
+    ? segments.at(-1)?.item.id
+    : [...segments].reverse().find((segment) => segment.display >= 0)?.item.id;
+  const lastNegativeId = shared
+    ? segments.at(-1)?.item.id
+    : [...segments].reverse().find((segment) => segment.display < 0)?.item.id;
+  const separated = stackGap > 0;
+  let positiveCursor = 0;
+  let negativeCursor = 0;
+  let positiveCount = 0;
+  let negativeCount = 0;
+
+  segments.forEach((segment) => {
+    const positive = segment.display >= 0;
+    const countBefore = shared
+      ? positiveCount + negativeCount
+      : positive
+        ? positiveCount
+        : negativeCount;
+    const gap = countBefore > 0 ? stackGap : 0;
+    if (positive) {
+      positiveCount += 1;
+    } else {
+      negativeCount += 1;
+    }
+    const rounded =
+      separated ||
+      (positive && segment.item.id === lastPositiveId) ||
+      (!positive && segment.item.id === lastNegativeId);
+    const from = shared || positive ? positiveCursor : negativeCursor;
+    const to = from + segment.display;
+    if (shared) {
+      positiveCursor = to;
+      negativeCursor = to;
+    } else if (positive) {
+      positiveCursor = to;
+    } else {
+      negativeCursor = to;
+    }
+    const base = {
+      index,
+      seriesId: segment.item.id,
+      seriesIndex: segment.seriesIndex,
+      label,
+      seriesLabel: segment.item.label,
+      value: segment.value,
+      plotValue: segment.display,
+      rounded,
+      roundAll: separated && countBefore > 0,
+      stackId: group.stackId,
+      ...(offset === 'expand' ? { expand: true } : {}),
+    };
+
+    if (orientation === 'vertical') {
+      const top = valueToY(Math.max(from, to));
+      const bottom = valueToY(Math.min(from, to));
+      bars.push({
+        ...base,
+        x: round2(plotX + index * band + groupOffset),
+        y: round2(positive ? top : top + gap),
+        width: round2(Math.max(thickness, 0)),
+        height: round2(Math.max(bottom - top - gap, 0)),
+      });
+      return;
+    }
+
+    const left = valueToX(Math.min(from, to));
+    const right = valueToX(Math.max(from, to));
+    bars.push({
+      ...base,
+      x: round2(positive ? left + gap : left),
+      y: round2(plotY + index * band + groupOffset),
+      width: round2(Math.max(right - left - gap, 0)),
+      height: round2(Math.max(thickness, 0)),
+    });
+  });
+}
+
+function waterfallRole(isTotal: boolean, delta: number): BarWaterfallRole {
+  if (isTotal) {
+    return 'total';
+  }
+  return delta >= 0 ? 'increase' : 'decrease';
+}
+
+function layoutWaterfallBar({
+  item,
+  label,
+  index,
+  orientation,
+  band,
+  groupOffset,
+  thickness,
+  plotX,
+  plotY,
+  from,
+  to,
+  delta,
+  role,
+  valueToX,
+  valueToY,
+}: {
+  readonly item: BarGeometrySeries;
+  readonly label: string;
+  readonly index: number;
+  readonly orientation: BarChartOrientation;
+  readonly band: number;
+  readonly groupOffset: number;
+  readonly thickness: number;
+  readonly plotX: number;
+  readonly plotY: number;
+  readonly from: number;
+  readonly to: number;
+  readonly delta: number;
+  readonly role: BarWaterfallRole;
+  readonly valueToX: (value: number) => number;
+  readonly valueToY: (value: number) => number;
+}): BarRect {
+  const low = Math.min(from, to);
+  const high = Math.max(from, to);
+  const base = {
+    index,
+    seriesId: item.id,
+    seriesIndex: index,
+    label,
+    seriesLabel: item.label,
+    value: role === 'total' ? to : delta,
+    plotValue: to - from,
+    rounded: true,
+    // Totals sit on the axis, so only the free end is rounded.
+    roundAll: role !== 'total',
+    waterfallRole: role,
+  };
+
+  if (orientation === 'vertical') {
+    const top = valueToY(high);
+    const bottom = valueToY(low);
+    return {
+      ...base,
+      x: round2(plotX + index * band + groupOffset),
+      y: round2(top),
+      width: round2(Math.max(thickness, 0)),
+      height: round2(Math.max(bottom - top, 0)),
+    };
+  }
+
+  const left = valueToX(low);
+  const right = valueToX(high);
+  return {
+    ...base,
+    x: round2(left),
+    y: round2(plotY + index * band + groupOffset),
+    width: round2(Math.max(right - left, 0)),
+    height: round2(Math.max(thickness, 0)),
+  };
+}
+
+function waterfallConnector(
+  fromBar: BarRect,
+  toBar: BarRect,
+  value: number,
+  orientation: BarChartOrientation,
+  valueToX: (value: number) => number,
+  valueToY: (value: number) => number,
+): BarGridLine {
+  if (orientation === 'vertical') {
+    const y = round2(valueToY(value));
+    return {
+      x1: round2(fromBar.x + fromBar.width),
+      y1: y,
+      x2: round2(toBar.x),
+      y2: y,
+    };
+  }
+  const x = round2(valueToX(value));
+  return {
+    x1: x,
+    y1: round2(fromBar.y + fromBar.height),
+    x2: x,
+    y2: round2(toBar.y),
+  };
+}
+
+export type BarShape = Pick<
+  BarRect,
+  'x' | 'y' | 'width' | 'height' | 'rounded' | 'value' | 'roundAll'
+>;
+
+export function barPath(bar: BarShape, orientation: BarChartOrientation, radius: number): string {
+  'worklet';
+  const { x, y, width, height } = bar;
+  if (width <= 0 || height <= 0) {
+    return '';
+  }
+
+  if (!bar.rounded) {
+    return `M ${String(x)} ${String(y)} L ${String(x + width)} ${String(y)} L ${String(x + width)} ${String(y + height)} L ${String(x)} ${String(y + height)} Z`;
+  }
+
+  if (bar.roundAll) {
+    const r = Math.min(radius, width / 2, height / 2);
+    const x2 = x + width;
+    const y2 = y + height;
+    return `M ${String(x + r)} ${String(y)} L ${String(x2 - r)} ${String(y)} Q ${String(x2)} ${String(y)} ${String(x2)} ${String(y + r)} L ${String(x2)} ${String(y2 - r)} Q ${String(x2)} ${String(y2)} ${String(x2 - r)} ${String(y2)} L ${String(x + r)} ${String(y2)} Q ${String(x)} ${String(y2)} ${String(x)} ${String(y2 - r)} L ${String(x)} ${String(y + r)} Q ${String(x)} ${String(y)} ${String(x + r)} ${String(y)} Z`;
+  }
+
+  const r =
+    orientation === 'vertical'
+      ? Math.min(radius, width / 2, height)
+      : Math.min(radius, height / 2, width);
+  const x2 = x + width;
+  const y2 = y + height;
+  const capPositive = bar.value >= 0;
+
+  if (orientation === 'vertical') {
+    if (capPositive) {
+      return `M ${String(x)} ${String(y2)} L ${String(x)} ${String(y + r)} Q ${String(x)} ${String(y)} ${String(x + r)} ${String(y)} L ${String(x2 - r)} ${String(y)} Q ${String(x2)} ${String(y)} ${String(x2)} ${String(y + r)} L ${String(x2)} ${String(y2)} Z`;
+    }
+    return `M ${String(x)} ${String(y)} L ${String(x2)} ${String(y)} L ${String(x2)} ${String(y2 - r)} Q ${String(x2)} ${String(y2)} ${String(x2 - r)} ${String(y2)} L ${String(x + r)} ${String(y2)} Q ${String(x)} ${String(y2)} ${String(x)} ${String(y2 - r)} Z`;
+  }
+
+  if (capPositive) {
+    return `M ${String(x)} ${String(y)} L ${String(x2 - r)} ${String(y)} Q ${String(x2)} ${String(y)} ${String(x2)} ${String(y + r)} L ${String(x2)} ${String(y2 - r)} Q ${String(x2)} ${String(y2)} ${String(x2 - r)} ${String(y2)} L ${String(x)} ${String(y2)} Z`;
+  }
+  return `M ${String(x2)} ${String(y)} L ${String(x2)} ${String(y2)} L ${String(x + r)} ${String(y2)} Q ${String(x)} ${String(y2)} ${String(x)} ${String(y2 - r)} L ${String(x)} ${String(y + r)} Q ${String(x)} ${String(y)} ${String(x + r)} ${String(y)} Z`;
+}
+
+const EMPTY_LAYOUT: BarChartLayout = {
+  bars: [],
+  categoryLabels: [],
+  valueTicks: [],
+  gridLines: [],
+  referenceLines: [],
+  connectors: [],
+  baseline: 0,
+  plot: { x: 0, y: 0, width: 0, height: 0 },
+};
+
+/** True when every stack group uses `expand`, so the value axis is a 0–1 share axis. */
+export function isExpandAxis(kind: BarChartKind, groups: readonly BarGroup[]): boolean {
+  return kind === 'bars' && groups.length > 0 && groups.every((group) => group.offset === 'expand');
+}
+
+export function layoutBarChart({
+  dataset,
+  categories,
+  series,
+  kind = 'bars',
+  waterfallTotalKey,
+  width,
+  height,
+  orientation,
+  barLabel,
+  categoryLabelPosition,
+  showTicks = true,
+  referenceLines = [],
+  valueAxis,
+  formatTick = formatBarValue,
+  stackGap = DEFAULT_STACK_GAP,
+  categoryGapRatio = CATEGORY_GAP_RATIO,
+  barGapRatio = BAR_GAP_RATIO,
+  showCategoryLabel,
+}: {
+  readonly dataset: readonly object[];
+  /** One name per row, from the category axis. Defaults to the row index. */
+  readonly categories?: readonly string[];
+  readonly series: readonly BarGeometrySeries[];
+  readonly kind?: BarChartKind;
+  /** Waterfall: row key whose `true` value marks a total bar. */
+  readonly waterfallTotalKey?: string;
+  readonly width: number;
+  readonly height: number;
+  readonly orientation: BarChartOrientation;
+  readonly barLabel: boolean;
+  readonly categoryLabelPosition?: BarChartCategoryLabelPosition;
+  readonly showTicks?: boolean;
+  readonly referenceLines?: readonly BarChartReferenceLine[];
+  readonly valueAxis?: BarValueAxisConfig;
+  /** Tick text. Receives a 0–1 share on an `expand` axis. */
+  readonly formatTick?: (value: number) => string;
+  readonly stackGap?: number;
+  readonly categoryGapRatio?: number;
+  readonly barGapRatio?: number;
+  /** Keeps the category name at `index` when it returns `true`. Others draw no text. */
+  readonly showCategoryLabel?: (index: number) => boolean;
+}): BarChartLayout {
+  if (width <= 0 || height <= 0 || dataset.length === 0 || series.length === 0) {
+    return EMPTY_LAYOUT;
+  }
+
+  const categoryOf = (index: number) => categories?.[index] ?? String(index);
+  const resolvedCategories = dataset.map((_, index) => categoryOf(index));
+  const overlay = kind === 'overlay';
+  const waterfall = kind === 'waterfall';
+  const groups = resolveBarGroups(series);
+  const expand = isExpandAxis(kind, groups);
+  const labels = resolveCategoryLabelPosition(orientation, categoryLabelPosition);
+  const { paddingLeft, paddingRight, paddingTop, paddingBottom } = resolveBarChartGutters({
+    categories: resolvedCategories,
+    hasNegative: dataset.some((row) =>
+      series.some((item) => (readBarValue(row, item.dataKey) ?? 0) < 0),
+    ),
+    orientation,
+    barLabel,
+    categoryLabelPosition: labels,
+    showTicks,
+    overlay,
+  });
+  const plot = {
+    x: paddingLeft,
+    y: paddingTop,
+    width: Math.max(width - paddingLeft - paddingRight, 0),
+    height: Math.max(height - paddingTop - paddingBottom, 0),
+  };
+
+  const waterfallSeries = series.at(0);
+  const dataValues = waterfall
+    ? collectWaterfallTotals(dataset, waterfallSeries?.dataKey ?? '', waterfallTotalKey)
+    : overlay
+      ? groupDomainValues(dataset, {
+          stackId: undefined,
+          offset: null,
+          members: series.map((item, seriesIndex) => ({ item, seriesIndex })),
+        })
+      : groups.flatMap((group) => groupDomainValues(dataset, group));
+  const values = [
+    ...dataValues,
+    ...referenceLines.flatMap((line) => (Number.isFinite(line.value) ? [line.value] : [])),
+  ];
+  const scale = resolveBarValueScale(values, valueAxis, expand);
+  const domainMin = scale.min;
+  const domainMax = scale.max;
+  const span = domainMax - domainMin || 1;
+  const categoryCount = dataset.length;
+  const slotCount = overlay || waterfall ? 1 : groups.length;
+  const band =
+    orientation === 'vertical' ? plot.width / categoryCount : plot.height / categoryCount;
+  const gapShare = clamp(
+    Number.isFinite(categoryGapRatio) ? categoryGapRatio : CATEGORY_GAP_RATIO,
+    0,
+    0.95,
+  );
+  const inner = band * (1 - gapShare);
+  const barGap = Math.max(Number.isFinite(barGapRatio) ? barGapRatio : BAR_GAP_RATIO, 0);
+  const gapSlots = Math.max(slotCount - 1, 0);
+  const thickness = inner / (slotCount + gapSlots * barGap);
+  const gap = gapSlots > 0 ? thickness * barGap : 0;
+  const groupOffset = (band - inner) / 2;
+
+  const toPlot = (value: number) => (clamp(value, domainMin, domainMax) - domainMin) / span;
+  const valueToY = (value: number) => plot.y + plot.height * (1 - toPlot(value));
+  const valueToX = (value: number) => plot.x + plot.width * toPlot(value);
+
+  const bars: BarRect[] = [];
+  const categoryLabels: BarLabelAnchor[] = [];
+  const connectors: BarGridLine[] = [];
+  let waterfallCursor = 0;
+  let waterfallPrev: { readonly bar: BarRect; readonly total: number } | null = null;
+
+  dataset.forEach((row, index) => {
+    const label = categoryOf(index);
+    const shownLabel = showCategoryLabel === undefined || showCategoryLabel(index) ? label : '';
+    // With `none`, category names still reach the tooltip and screen readers through the bars.
+    if (labels !== 'none' && orientation === 'vertical') {
+      const center = plot.x + index * band + band / 2;
+      const halfWidth = (shownLabel.length * CATEGORY_LABEL_CHAR_WIDTH) / 2;
+      const anchor =
+        center - halfWidth < plot.x
+          ? { x: plot.x, textAnchor: 'start' as const }
+          : center + halfWidth > plot.x + plot.width
+            ? { x: plot.x + plot.width, textAnchor: 'end' as const }
+            : { x: center, textAnchor: 'middle' as const };
+      categoryLabels.push({
+        label: shownLabel,
+        x: round2(anchor.x),
+        y: round2(labels === 'top' ? paddingTop / 2 : height - 8),
+        textAnchor: anchor.textAnchor,
+      });
+    } else if (labels !== 'none') {
+      categoryLabels.push({
+        label: shownLabel,
+        x: round2(labels === 'right' ? plot.x + plot.width + 8 : plot.x - 8),
+        y: round2(plot.y + index * band + band / 2),
+        textAnchor: labels === 'right' ? 'start' : 'end',
+      });
+    }
+
+    if (waterfall) {
+      if (waterfallSeries === undefined) {
+        return;
+      }
+      const isTotal = readBarFlag(row, waterfallTotalKey);
+      const raw = readBarValue(row, waterfallSeries.dataKey);
+      if (!isTotal && raw === null) {
+        return;
+      }
+      const from = isTotal ? 0 : waterfallCursor;
+      if (isTotal) {
+        if (raw !== null && index === 0) {
+          waterfallCursor = raw;
+        }
+      } else if (raw !== null) {
+        waterfallCursor += raw;
+      }
+      const to = waterfallCursor;
+      const delta = isTotal ? to : (raw ?? 0);
+      const bar = layoutWaterfallBar({
+        item: waterfallSeries,
+        label,
+        index,
+        orientation,
+        band,
+        groupOffset,
+        thickness,
+        plotX: plot.x,
+        plotY: plot.y,
+        from,
+        to,
+        delta,
+        role: waterfallRole(isTotal, delta),
+        valueToX,
+        valueToY,
+      });
+      if (waterfallPrev !== null) {
+        connectors.push(
+          waterfallConnector(
+            waterfallPrev.bar,
+            bar,
+            waterfallPrev.total,
+            orientation,
+            valueToX,
+            valueToY,
+          ),
+        );
+      }
+      bars.push(bar);
+      waterfallPrev = { bar, total: to };
+      return;
+    }
+
+    if (overlay) {
+      series.forEach((item, seriesIndex) => {
+        const value = readBarValue(row, item.dataKey);
+        if (value === null) {
+          return;
+        }
+        bars.push(
+          overlayRect({
+            index,
+            seriesIndex,
+            item,
+            label,
+            value,
+            orientation,
+            band,
+            groupOffset,
+            inner,
+            plotX: plot.x,
+            plotY: plot.y,
+            valueToX,
+            valueToY,
+          }),
+        );
+      });
+      return;
+    }
+
+    groups.forEach((group, slot) => {
+      const slotOffset = groupOffset + slot * (thickness + gap);
+      if (group.stackId !== undefined) {
+        layoutStackedRow({
+          row,
+          label,
+          index,
+          group,
+          orientation,
+          band,
+          groupOffset: slotOffset,
+          thickness,
+          plotX: plot.x,
+          plotY: plot.y,
+          valueToX,
+          valueToY,
+          bars,
+          stackGap: Math.max(stackGap, 0),
+        });
+        return;
+      }
+      const member = group.members.at(0);
+      if (member === undefined) {
+        return;
+      }
+      const value = readBarValue(row, member.item.dataKey);
+      if (value === null) {
+        return;
+      }
+      bars.push(
+        groupedRect({
+          index,
+          seriesIndex: member.seriesIndex,
+          slot,
+          item: member.item,
+          label,
+          value,
+          orientation,
+          band,
+          groupOffset,
+          thickness,
+          gap,
+          plotX: plot.x,
+          plotY: plot.y,
+          valueToX,
+          valueToY,
+        }),
+      );
+    });
+  });
+
+  const tickText = (value: number) => formatTick(expand ? value / 100 : value);
+  const valueTicks: BarValueTick[] = scale.ticks.map((value) => {
+    if (orientation === 'vertical') {
+      return {
+        value,
+        x: round2(plot.x - 8),
+        y: round2(valueToY(value)),
+        text: tickText(value),
+      };
+    }
+    return {
+      value,
+      x: round2(valueToX(value)),
+      y: round2(height - 8),
+      text: tickText(value),
+    };
+  });
+
+  const gridLines: BarGridLine[] = scale.ticks.map((value) => {
+    if (orientation === 'vertical') {
+      const y = round2(valueToY(value));
+      return { x1: round2(plot.x), y1: y, x2: round2(plot.x + plot.width), y2: y };
+    }
+    const x = round2(valueToX(value));
+    return { x1: x, y1: round2(plot.y), x2: x, y2: round2(plot.y + plot.height) };
+  });
+
+  const zero = clamp(0, domainMin, domainMax);
+  const baseline = round2(orientation === 'vertical' ? valueToY(zero) : valueToX(zero));
+
+  const laidReferenceLines: BarReferenceLineLayout[] = referenceLines.flatMap((line) => {
+    if (!Number.isFinite(line.value) || line.value < domainMin || line.value > domainMax) {
+      return [];
+    }
+    if (orientation === 'vertical') {
+      const y = round2(valueToY(line.value));
+      return [
+        {
+          x1: round2(plot.x),
+          y1: y,
+          x2: round2(plot.x + plot.width),
+          y2: y,
+          label: line.label,
+        },
+      ];
+    }
+    const x = round2(valueToX(line.value));
+    return [
+      {
+        x1: x,
+        y1: round2(plot.y),
+        x2: x,
+        y2: round2(plot.y + plot.height),
+        label: line.label,
+      },
+    ];
+  });
+
+  return {
+    bars,
+    categoryLabels,
+    valueTicks,
+    gridLines,
+    referenceLines: laidReferenceLines,
+    connectors,
+    baseline,
+    plot,
+  };
+}
+
+export function overlayDelta(bars: readonly BarRect[], index: number): number | null {
+  const group = bars.filter((bar) => bar.index === index);
+  const primary = group.find((bar) => bar.seriesIndex === 0);
+  const comparison = group.find((bar) => bar.seriesIndex === 1);
+  if (primary === undefined || comparison === undefined) {
+    return null;
+  }
+  return round2(primary.value - comparison.value);
+}
+
+/** Waterfall steps read as signed changes; totals read as the running total. */
+export function formatWaterfallBarValue(
+  bar: Pick<BarRect, 'value' | 'waterfallRole'>,
+  formatValue: (value: number) => string,
+): string {
+  if (bar.waterfallRole === 'increase') {
+    return `+${formatValue(bar.value)}`;
+  }
+  if (bar.waterfallRole === 'decrease') {
+    return `-${formatValue(Math.abs(bar.value))}`;
+  }
+  return formatValue(bar.value);
+}
+
+export function waterfallValueAnchor(
+  bar: BarRect,
+  orientation: BarChartOrientation,
+): { readonly x: number; readonly y: number; readonly textAnchor: 'start' | 'middle' | 'end' } {
+  if (orientation === 'vertical') {
+    return {
+      x: round2(bar.x + bar.width / 2),
+      y: round2(bar.y - 4),
+      textAnchor: 'middle',
+    };
+  }
+  return {
+    x: round2(bar.x + bar.width + 4),
+    y: round2(bar.y + bar.height / 2),
+    textAnchor: 'start',
+  };
+}
+
+export function barValueAnchor(
+  bar: BarRect,
+  orientation: BarChartOrientation,
+): { readonly x: number; readonly y: number; readonly textAnchor: 'start' | 'middle' | 'end' } {
+  if (orientation === 'vertical') {
+    return {
+      x: round2(bar.x + bar.width / 2),
+      y: round2(bar.plotValue >= 0 ? Math.max(bar.y - 12, 12) : bar.y + bar.height + 12),
+      textAnchor: 'middle',
+    };
+  }
+  return {
+    x: round2(bar.plotValue >= 0 ? bar.x + bar.width + 4 : bar.x - 4),
+    y: round2(bar.y + bar.height / 2),
+    textAnchor: bar.plotValue >= 0 ? 'start' : 'end',
+  };
+}
+
+export interface BarStackTotalAnchor {
+  readonly key: string;
+  readonly index: number;
+  readonly x: number;
+  readonly y: number;
+  readonly textAnchor: 'start' | 'middle' | 'end';
+  /** Sum of the stack's plotted values (a 0–100 share total when `expand`). */
+  readonly total: number;
+  readonly expand: boolean;
+  /** Series of the outer segment. Its formatter labels the total. */
+  readonly seriesId: string;
+}
+
+/** One total label per stack in each category. */
+export function stackedTotalAnchors(
+  bars: readonly BarRect[],
+  orientation: BarChartOrientation,
+): readonly BarStackTotalAnchor[] {
+  const byStack = new Map<string, BarRect[]>();
+  bars.forEach((bar) => {
+    if (bar.stackId === undefined) {
+      return;
+    }
+    const key = `${String(bar.index)}:${bar.stackId}`;
+    const group = byStack.get(key) ?? [];
+    group.push(bar);
+    byStack.set(key, group);
+  });
+
+  return [...byStack.entries()].flatMap(([key, group]) => {
+    const outer = group.filter((bar) => bar.plotValue >= 0).at(-1) ?? group.at(-1);
+    if (outer === undefined) {
+      return [];
+    }
+    const total = group.reduce((sum, bar) => sum + bar.plotValue, 0);
+    const anchor = barValueAnchor({ ...outer, plotValue: total, value: total }, orientation);
+    return [
+      {
+        key,
+        index: outer.index,
+        ...anchor,
+        total,
+        expand: outer.expand === true,
+        seriesId: outer.seriesId,
+      },
+    ];
+  });
+}
+
+/**
+ * Next bar for keyboard movement. Along the category axis keeps the same series; along the
+ * value axis steps series inside the category. Home / End jump the category axis.
+ */
+export function barKeyboardNeighbor(
+  bars: readonly Pick<BarRect, 'index' | 'seriesIndex'>[],
+  from: number,
+  key: string,
+  orientation: BarChartOrientation,
+): number | null {
+  const current = bars[from];
+  if (current === undefined) {
+    return null;
+  }
+  const categories = [...new Set(bars.map((bar) => bar.index))];
+  const categoryPos = categories.indexOf(current.index);
+  const seriesInCategory = bars
+    .map((bar, index) => ({ bar, index }))
+    .filter((item) => item.bar.index === current.index);
+  const seriesPos = seriesInCategory.findIndex((item) => item.index === from);
+  const alongCategory =
+    key === 'Tab'
+      ? 1
+      : key === 'Shift+Tab'
+        ? -1
+        : orientation === 'vertical'
+          ? key === 'ArrowRight' || key === 'End'
+            ? 1
+            : key === 'ArrowLeft' || key === 'Home'
+              ? -1
+              : 0
+          : key === 'ArrowDown' || key === 'End'
+            ? 1
+            : key === 'ArrowUp' || key === 'Home'
+              ? -1
+              : 0;
+  const alongSeries =
+    orientation === 'vertical'
+      ? key === 'ArrowDown'
+        ? 1
+        : key === 'ArrowUp'
+          ? -1
+          : 0
+      : key === 'ArrowRight'
+        ? 1
+        : key === 'ArrowLeft'
+          ? -1
+          : 0;
+
+  if (key === 'Home' || key === 'End') {
+    const nextCategory = alongCategory > 0 ? categories.at(-1) : categories[0];
+    if (nextCategory === undefined) {
+      return from;
+    }
+    const match = bars.findIndex(
+      (bar) => bar.index === nextCategory && bar.seriesIndex === current.seriesIndex,
+    );
+    return match >= 0 ? match : bars.findIndex((bar) => bar.index === nextCategory);
+  }
+
+  if (alongCategory !== 0) {
+    const nextCategory = categories[categoryPos + alongCategory];
+    if (nextCategory === undefined) {
+      return from;
+    }
+    const match = bars.findIndex(
+      (bar) => bar.index === nextCategory && bar.seriesIndex === current.seriesIndex,
+    );
+    return match >= 0 ? match : bars.findIndex((bar) => bar.index === nextCategory);
+  }
+
+  if (alongSeries !== 0) {
+    const next = seriesInCategory[seriesPos + alongSeries];
+    return next === undefined ? from : next.index;
+  }
+
+  return null;
+}