insomni-plot 0.1.0-alpha.0

package/src/scales.ts

@@ -0,0 +1,695 @@
+export type NumericRange = readonly [number, number];
+export type NumericDomain = readonly [number, number];
+export type DateDomain = readonly [Date, Date];
+export type TickFormatter<T> = (value: T) => string;
+
+export interface ContinuousScale {
+  (value: number): number;
+  readonly domain: NumericDomain;
+  readonly range: NumericRange;
+  invert(value: number): number;
+  ticks(count?: number): readonly number[];
+  tickFormat(count?: number): TickFormatter<number>;
+}
+
+export interface TimeScale {
+  (value: Date): number;
+  readonly domain: DateDomain;
+  readonly range: NumericRange;
+  invert(value: number): Date;
+  ticks(count?: number): readonly Date[];
+  tickFormat(count?: number): TickFormatter<Date>;
+}
+
+export interface BandScale<Domain> {
+  (value: Domain): number;
+  readonly domain: readonly Domain[];
+  readonly range: NumericRange;
+  bandwidth(): number;
+  step(): number;
+  ticks(): readonly Domain[];
+  tickFormat(): TickFormatter<Domain>;
+}
+
+export type AxisScale<Value> = ContinuousScale | TimeScale | BandScale<Value>;
+
+export interface BandScaleOptions {
+  padding?: number;
+  paddingInner?: number;
+  paddingOuter?: number;
+  align?: number;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const MONTH_NAMES = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec",
+];
+
+/**
+ * Time interval units accepted by {@link timeTicks} / {@link timeTickFormat}
+ * and by axis `ticks: { interval, step }` specs. `quarter` is sugar for
+ * `month` with step `3 × step`.
+ */
+export type TimeIntervalUnit =
+  | "millisecond"
+  | "second"
+  | "minute"
+  | "hour"
+  | "day"
+  | "week"
+  | "month"
+  | "quarter"
+  | "year";
+
+type InternalTimeUnit = Exclude<TimeIntervalUnit, "quarter">;
+
+interface TimeIntervalDef {
+  readonly unit: InternalTimeUnit;
+  readonly step: number;
+  readonly approxMs: number;
+}
+
+const APPROX_MS_BY_UNIT: Record<InternalTimeUnit, number> = {
+  millisecond: 1,
+  second: 1000,
+  minute: 60_000,
+  hour: 3_600_000,
+  day: DAY_MS,
+  week: WEEK_MS,
+  month: 30 * DAY_MS,
+  year: 365 * DAY_MS,
+};
+
+function resolveInterval(unit: TimeIntervalUnit, step = 1): TimeIntervalDef {
+  const cleanStep = Math.max(1, Math.floor(step));
+  if (unit === "quarter") {
+    return {
+      unit: "month",
+      step: 3 * cleanStep,
+      approxMs: 3 * cleanStep * APPROX_MS_BY_UNIT.month,
+    };
+  }
+  return { unit, step: cleanStep, approxMs: cleanStep * APPROX_MS_BY_UNIT[unit] };
+}
+
+const TIME_INTERVALS: readonly TimeIntervalDef[] = [
+  { unit: "millisecond", step: 1, approxMs: 1 },
+  { unit: "millisecond", step: 5, approxMs: 5 },
+  { unit: "millisecond", step: 10, approxMs: 10 },
+  { unit: "millisecond", step: 50, approxMs: 50 },
+  { unit: "millisecond", step: 100, approxMs: 100 },
+  { unit: "millisecond", step: 250, approxMs: 250 },
+  { unit: "millisecond", step: 500, approxMs: 500 },
+  { unit: "second", step: 1, approxMs: 1000 },
+  { unit: "second", step: 5, approxMs: 5000 },
+  { unit: "second", step: 15, approxMs: 15_000 },
+  { unit: "second", step: 30, approxMs: 30_000 },
+  { unit: "minute", step: 1, approxMs: 60_000 },
+  { unit: "minute", step: 5, approxMs: 300_000 },
+  { unit: "minute", step: 15, approxMs: 900_000 },
+  { unit: "minute", step: 30, approxMs: 1_800_000 },
+  { unit: "hour", step: 1, approxMs: 3_600_000 },
+  { unit: "hour", step: 3, approxMs: 10_800_000 },
+  { unit: "hour", step: 6, approxMs: 21_600_000 },
+  { unit: "hour", step: 12, approxMs: 43_200_000 },
+  { unit: "day", step: 1, approxMs: DAY_MS },
+  { unit: "day", step: 2, approxMs: 2 * DAY_MS },
+  { unit: "week", step: 1, approxMs: WEEK_MS },
+  { unit: "month", step: 1, approxMs: 30 * DAY_MS },
+  { unit: "month", step: 3, approxMs: 91 * DAY_MS },
+  { unit: "month", step: 6, approxMs: 182 * DAY_MS },
+  { unit: "year", step: 1, approxMs: 365 * DAY_MS },
+  { unit: "year", step: 2, approxMs: 2 * 365 * DAY_MS },
+  { unit: "year", step: 5, approxMs: 5 * 365 * DAY_MS },
+  { unit: "year", step: 10, approxMs: 10 * 365 * DAY_MS },
+  { unit: "year", step: 25, approxMs: 25 * 365 * DAY_MS },
+  { unit: "year", step: 50, approxMs: 50 * 365 * DAY_MS },
+  { unit: "year", step: 100, approxMs: 100 * 365 * DAY_MS },
+];
+
+function validateNumberPair(name: string, pair: readonly [number, number]): NumericDomain {
+  if (!Number.isFinite(pair[0]) || !Number.isFinite(pair[1])) {
+    throw new Error(`${name} values must be finite numbers.`);
+  }
+  return [pair[0], pair[1]];
+}
+
+function validateDatePair(domain: readonly [Date, Date]): DateDomain {
+  const start = domain[0].getTime();
+  const stop = domain[1].getTime();
+  if (!Number.isFinite(start) || !Number.isFinite(stop)) {
+    throw new Error("timeScale domain values must be valid Date instances.");
+  }
+  return [new Date(start), new Date(stop)];
+}
+
+function normalize(value: number, start: number, stop: number): number {
+  if (!Number.isFinite(value)) return Number.NaN;
+  if (stop === start) return 0.5;
+  return (value - start) / (stop - start);
+}
+
+function interpolate(start: number, stop: number, t: number): number {
+  return start + (stop - start) * t;
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function roundNumber(value: number, digits = 12): number {
+  return Number.parseFloat(value.toPrecision(digits));
+}
+
+function stripTrailingZeros(value: string): string {
+  return value
+    .replace(/(\.\d*?[1-9])0+$/u, "$1")
+    .replace(/\.0+$/u, "")
+    .replace(/\.e/u, "e");
+}
+
+function formatNumber(value: number, fractionDigits: number): string {
+  const normalized = Object.is(value, -0) ? 0 : value;
+  const abs = Math.abs(normalized);
+  if (abs >= 1e7 || (abs > 0 && abs < 1e-4)) {
+    return stripTrailingZeros(normalized.toExponential(2));
+  }
+  return stripTrailingZeros(normalized.toFixed(fractionDigits));
+}
+
+function tickStep(start: number, stop: number, count: number): number {
+  const steps = Math.max(count, 1);
+  const span = Math.abs(stop - start);
+  if (span === 0) return 0;
+
+  const step0 = span / steps;
+  const power = Math.floor(Math.log10(step0));
+  const power10 = 10 ** power;
+  const error = step0 / power10;
+
+  let factor = 1;
+  if (error >= Math.sqrt(50)) {
+    factor = 10;
+  } else if (error >= Math.sqrt(10)) {
+    factor = 5;
+  } else if (error >= Math.sqrt(2)) {
+    factor = 2;
+  }
+
+  return factor * power10;
+}
+
+export function numericTicks(start: number, stop: number, count = 5): readonly number[] {
+  if (count <= 0) return [];
+  if (start === stop) return [start];
+
+  const reverse = stop < start;
+  const min = reverse ? stop : start;
+  const max = reverse ? start : stop;
+  const step = tickStep(min, max, count);
+  if (!Number.isFinite(step) || step === 0) return [start];
+
+  const epsilon = step * 1e-9;
+  const first = Math.ceil((min - epsilon) / step);
+  const last = Math.floor((max + epsilon) / step);
+  const ticks: number[] = [];
+
+  for (let index = first; index <= last; index++) {
+    ticks.push(roundNumber(index * step));
+  }
+
+  return reverse ? ticks.reverse() : ticks;
+}
+
+function inferFractionDigits(step: number): number {
+  if (!Number.isFinite(step) || step === 0) return 0;
+  return Math.max(0, Math.ceil(-Math.log10(Math.abs(step))));
+}
+
+function inferTickStep(values: readonly number[]): number {
+  if (values.length < 2) return 0;
+  let step = Number.POSITIVE_INFINITY;
+  for (let index = 1; index < values.length; index++) {
+    const delta = Math.abs(values[index] - values[index - 1]);
+    if (delta > 0) {
+      step = Math.min(step, delta);
+    }
+  }
+  return Number.isFinite(step) ? step : 0;
+}
+
+function numericTickFormatter(values: readonly number[]): TickFormatter<number> {
+  const digits = inferFractionDigits(inferTickStep(values));
+  return (value: number) => formatNumber(value, digits);
+}
+
+/** Sign-preserving sqrt: f(-x) = -sqrt(x). Used by `sqrtScale` and viewport. */
+export function signedSqrt(value: number): number {
+  return Math.sign(value) * Math.sqrt(Math.abs(value));
+}
+
+/** Inverse of `signedSqrt`. */
+export function signedSquare(value: number): number {
+  return Math.sign(value) * value * value;
+}
+
+function createContinuousScale(
+  domain: NumericDomain,
+  range: NumericRange,
+  transform: (value: number) => number,
+  untransform: (value: number) => number,
+  ticks: (count?: number) => readonly number[],
+): ContinuousScale {
+  const [d0, d1] = domain;
+  const [r0, r1] = range;
+  const td0 = transform(d0);
+  const td1 = transform(d1);
+
+  const scale = ((value: number) => {
+    const t = normalize(transform(value), td0, td1);
+    return interpolate(r0, r1, t);
+  }) as ContinuousScale;
+
+  Object.defineProperties(scale, {
+    domain: { value: [d0, d1] as const, enumerable: true },
+    range: { value: [r0, r1] as const, enumerable: true },
+  });
+
+  scale.invert = (value: number) => {
+    const t = normalize(value, r0, r1);
+    return untransform(interpolate(td0, td1, t));
+  };
+  scale.ticks = (count = 5) => ticks(count);
+  scale.tickFormat = (count = 5) => numericTickFormatter(scale.ticks(count));
+
+  return scale;
+}
+
+export function linearScale(domain: NumericDomain, range: NumericRange): ContinuousScale {
+  return createContinuousScale(
+    validateNumberPair("linearScale domain", domain),
+    validateNumberPair("linearScale range", range),
+    (value) => value,
+    (value) => value,
+    (count) => numericTicks(domain[0], domain[1], count),
+  );
+}
+
+export function sqrtScale(domain: NumericDomain, range: NumericRange): ContinuousScale {
+  const validatedDomain = validateNumberPair("sqrtScale domain", domain);
+  return createContinuousScale(
+    validatedDomain,
+    validateNumberPair("sqrtScale range", range),
+    signedSqrt,
+    signedSquare,
+    (count) => numericTicks(validatedDomain[0], validatedDomain[1], count),
+  );
+}
+
+/** Sign-preserving log. Used by `logScale` and viewport transforms. */
+export function logTransform(value: number): number {
+  return Math.sign(value) * Math.log(Math.abs(value));
+}
+
+/** Inverse of `logTransform`. */
+export function logUntransform(value: number): number {
+  return Math.sign(value) * Math.exp(Math.abs(value));
+}
+
+function logTicks(start: number, stop: number, count = 5): readonly number[] {
+  if (count <= 0) return [];
+  if (start === stop) return [start];
+
+  const reverse = stop < start;
+  const sign = start < 0 ? -1 : 1;
+  const min = Math.min(Math.abs(start), Math.abs(stop));
+  const max = Math.max(Math.abs(start), Math.abs(stop));
+  const useSubdivisions = Math.abs(Math.log10(max) - Math.log10(min)) <= count;
+  const multipliers = useSubdivisions ? [1, 2, 5] : [1];
+  const minExp = Math.floor(Math.log10(min));
+  const maxExp = Math.ceil(Math.log10(max));
+  const ticks: number[] = [];
+
+  for (let exponent = minExp; exponent <= maxExp; exponent++) {
+    const base = 10 ** exponent;
+    for (const multiplier of multipliers) {
+      const value = sign * multiplier * base;
+      const magnitude = Math.abs(value);
+      if (magnitude >= min * 0.999999999 && magnitude <= max * 1.000000001) {
+        ticks.push(value);
+      }
+    }
+  }
+
+  if (ticks.length === 0) {
+    return numericTicks(start, stop, count);
+  }
+
+  const deduped = ticks
+    .sort((a, b) => a - b)
+    .filter((value, index, values) => index === 0 || Math.abs(value - values[index - 1]) > 1e-9);
+
+  return reverse ? deduped.reverse() : deduped;
+}
+
+export function logScale(domain: NumericDomain, range: NumericRange): ContinuousScale {
+  const validatedDomain = validateNumberPair("logScale domain", domain);
+  const [d0, d1] = validatedDomain;
+  if (d0 === 0 || d1 === 0) {
+    throw new Error("logScale domain values must be non-zero.");
+  }
+  if (Math.sign(d0) !== Math.sign(d1)) {
+    throw new Error("logScale domain values must share the same sign.");
+  }
+
+  return createContinuousScale(
+    validatedDomain,
+    validateNumberPair("logScale range", range),
+    logTransform,
+    logUntransform,
+    (count) => logTicks(validatedDomain[0], validatedDomain[1], count),
+  );
+}
+
+function chooseTimeInterval(start: Date, stop: Date, count = 5): TimeIntervalDef {
+  const target = Math.abs(stop.getTime() - start.getTime()) / Math.max(count, 1);
+  for (const interval of TIME_INTERVALS) {
+    if (target <= interval.approxMs) return interval;
+  }
+  return TIME_INTERVALS[TIME_INTERVALS.length - 1]!;
+}
+
+function floorUtc(date: Date, interval: TimeIntervalDef): Date {
+  const value = new Date(date.getTime());
+  switch (interval.unit) {
+    case "millisecond":
+      value.setTime(Math.floor(value.getTime() / interval.step) * interval.step);
+      return value;
+    case "second":
+      value.setUTCMilliseconds(0);
+      value.setUTCSeconds(Math.floor(value.getUTCSeconds() / interval.step) * interval.step);
+      return value;
+    case "minute":
+      value.setUTCMilliseconds(0);
+      value.setUTCSeconds(0);
+      value.setUTCMinutes(Math.floor(value.getUTCMinutes() / interval.step) * interval.step);
+      return value;
+    case "hour":
+      value.setUTCMilliseconds(0);
+      value.setUTCSeconds(0);
+      value.setUTCMinutes(0);
+      value.setUTCHours(Math.floor(value.getUTCHours() / interval.step) * interval.step);
+      return value;
+    case "day":
+      value.setUTCHours(0, 0, 0, 0);
+      value.setTime(
+        Math.floor(value.getTime() / (interval.step * DAY_MS)) * interval.step * DAY_MS,
+      );
+      return value;
+    case "week":
+      value.setUTCHours(0, 0, 0, 0);
+      value.setUTCDate(value.getUTCDate() - ((value.getUTCDay() + 6) % 7));
+      value.setTime(
+        Math.floor(value.getTime() / (interval.step * WEEK_MS)) * interval.step * WEEK_MS,
+      );
+      return value;
+    case "month":
+      value.setUTCHours(0, 0, 0, 0);
+      value.setUTCDate(1);
+      value.setUTCMonth(Math.floor(value.getUTCMonth() / interval.step) * interval.step);
+      return value;
+    case "year":
+      value.setUTCHours(0, 0, 0, 0);
+      value.setUTCDate(1);
+      value.setUTCMonth(0);
+      value.setUTCFullYear(Math.floor(value.getUTCFullYear() / interval.step) * interval.step);
+      return value;
+  }
+}
+
+function offsetUtc(date: Date, interval: TimeIntervalDef): Date {
+  const value = new Date(date.getTime());
+  switch (interval.unit) {
+    case "millisecond":
+      value.setTime(value.getTime() + interval.step);
+      return value;
+    case "second":
+      value.setUTCSeconds(value.getUTCSeconds() + interval.step);
+      return value;
+    case "minute":
+      value.setUTCMinutes(value.getUTCMinutes() + interval.step);
+      return value;
+    case "hour":
+      value.setUTCHours(value.getUTCHours() + interval.step);
+      return value;
+    case "day":
+      value.setUTCDate(value.getUTCDate() + interval.step);
+      return value;
+    case "week":
+      value.setUTCDate(value.getUTCDate() + interval.step * 7);
+      return value;
+    case "month":
+      value.setUTCMonth(value.getUTCMonth() + interval.step);
+      return value;
+    case "year":
+      value.setUTCFullYear(value.getUTCFullYear() + interval.step);
+      return value;
+  }
+}
+
+function formatUtcDate(date: Date, interval: TimeIntervalDef): string {
+  const month = MONTH_NAMES[date.getUTCMonth()] ?? "";
+  const day = date.getUTCDate();
+  const year = date.getUTCFullYear();
+  const hours = String(date.getUTCHours()).padStart(2, "0");
+  const minutes = String(date.getUTCMinutes()).padStart(2, "0");
+  const seconds = String(date.getUTCSeconds()).padStart(2, "0");
+  const millis = String(date.getUTCMilliseconds()).padStart(3, "0");
+
+  switch (interval.unit) {
+    case "year":
+      return String(year);
+    case "month":
+      return `${month} ${year}`;
+    case "week":
+    case "day":
+      return `${month} ${day}`;
+    case "hour":
+      return `${hours}:00`;
+    case "minute":
+      return `${hours}:${minutes}`;
+    case "second":
+      return `${hours}:${minutes}:${seconds}`;
+    case "millisecond":
+      return `${hours}:${minutes}:${seconds}.${millis}`;
+  }
+}
+
+export function timeScale(domain: DateDomain, range: NumericRange): TimeScale {
+  const validatedDomain = validateDatePair(domain);
+  const [start, stop] = validatedDomain;
+  const [r0, r1] = validateNumberPair("timeScale range", range);
+  const startMs = start.getTime();
+  const stopMs = stop.getTime();
+
+  const scale = ((value: Date) => {
+    const t = normalize(value.getTime(), startMs, stopMs);
+    return interpolate(r0, r1, t);
+  }) as TimeScale;
+
+  Object.defineProperties(scale, {
+    domain: { value: [new Date(startMs), new Date(stopMs)] as const, enumerable: true },
+    range: { value: [r0, r1] as const, enumerable: true },
+  });
+
+  scale.invert = (value: number) => {
+    const t = normalize(value, r0, r1);
+    return new Date(interpolate(startMs, stopMs, t));
+  };
+
+  scale.ticks = (count = 5) => {
+    if (count <= 0) return [];
+    if (startMs === stopMs) return [new Date(startMs)];
+
+    const reverse = stopMs < startMs;
+    const lo = reverse ? new Date(stopMs) : new Date(startMs);
+    const hi = reverse ? new Date(startMs) : new Date(stopMs);
+    const interval = chooseTimeInterval(lo, hi, count);
+    return generateTimeTicks(lo, hi, interval, reverse);
+  };
+
+  scale.tickFormat = (count = 5) => {
+    const interval = chooseTimeInterval(start, stop, count);
+    return (value: Date) => formatUtcDate(value, interval);
+  };
+
+  return scale;
+}
+
+function generateTimeTicks(
+  lo: Date,
+  hi: Date,
+  interval: TimeIntervalDef,
+  reverse: boolean,
+): readonly Date[] {
+  let cursor = floorUtc(lo, interval);
+  if (cursor.getTime() < lo.getTime()) {
+    cursor = offsetUtc(cursor, interval);
+  }
+  const ticks: Date[] = [];
+  while (cursor.getTime() <= hi.getTime() && ticks.length < 10_000) {
+    ticks.push(new Date(cursor.getTime()));
+    cursor = offsetUtc(cursor, interval);
+  }
+  return reverse ? ticks.reverse() : ticks;
+}
+
+/**
+ * Generate UTC tick dates at an explicit interval (e.g. every month, every
+ * 3 weeks, every quarter). Use this when the default `timeScale.ticks(count)`
+ * heuristic picks the wrong granularity for a known cadence. `step` defaults
+ * to `1`. `quarter` is sugar for `month, step: 3`.
+ */
+export function timeTicks(domain: DateDomain, unit: TimeIntervalUnit, step = 1): readonly Date[] {
+  const validated = validateDatePair(domain);
+  const [start, stop] = validated;
+  const startMs = start.getTime();
+  const stopMs = stop.getTime();
+  if (startMs === stopMs) return [new Date(startMs)];
+  const reverse = stopMs < startMs;
+  const lo = reverse ? stop : start;
+  const hi = reverse ? start : stop;
+  return generateTimeTicks(lo, hi, resolveInterval(unit, step), reverse);
+}
+
+/**
+ * Tick formatter paired with {@link timeTicks}. The label shape is picked
+ * from the unit: years render `"2026"`, months `"Mar 2026"`, days `"Mar 14"`,
+ * etc. — matching the formatter used by {@link timeScale}.
+ */
+export function timeTickFormat(unit: TimeIntervalUnit, step = 1): TickFormatter<Date> {
+  const interval = resolveInterval(unit, step);
+  return (value: Date) => formatUtcDate(value, interval);
+}
+
+export function bandScale<Domain>(
+  domain: readonly Domain[],
+  range: NumericRange,
+  options: BandScaleOptions = {},
+): BandScale<Domain> {
+  const validatedRange = validateNumberPair("bandScale range", range);
+  const [r0, r1] = validatedRange;
+  const reverse = r1 < r0;
+  const start = reverse ? r1 : r0;
+  const stop = reverse ? r0 : r1;
+  const paddingInner = clamp(options.paddingInner ?? options.padding ?? 0, 0, 1);
+  const paddingOuter = Math.max(options.paddingOuter ?? options.padding ?? 0, 0);
+  const align = clamp(options.align ?? 0.5, 0, 1);
+  const count = domain.length;
+  const denominator = Math.max(1, count - paddingInner + paddingOuter * 2);
+  const stepValue = count === 0 ? 0 : (stop - start) / denominator;
+  const bandwidthValue = stepValue * (1 - paddingInner);
+  const offset = (stop - start - stepValue * (count - paddingInner)) * align;
+  const first = start + offset + stepValue * paddingOuter;
+  const index = new Map<Domain, number>();
+
+  for (let position = 0; position < domain.length; position++) {
+    const value = domain[position]!;
+    if (index.has(value)) {
+      throw new Error("bandScale domain values must be unique.");
+    }
+    index.set(value, position);
+  }
+
+  const scale = ((value: Domain) => {
+    const position = index.get(value);
+    if (position === undefined) return Number.NaN;
+
+    const x = first + stepValue * position;
+    if (!reverse) return x;
+    return r0 - (x - start) - bandwidthValue;
+  }) as BandScale<Domain>;
+
+  Object.defineProperties(scale, {
+    domain: { value: [...domain], enumerable: true },
+    range: { value: [r0, r1] as const, enumerable: true },
+  });
+
+  scale.bandwidth = () => bandwidthValue;
+  scale.step = () => stepValue;
+  scale.ticks = () => [...domain];
+  scale.tickFormat = () => (value: Domain) => String(value);
+
+  return scale;
+}
+
+// ---------------------------------------------------------------------------
+// groupedBandScale — nested band layout for grouped bars
+// ---------------------------------------------------------------------------
+
+export interface GroupedBandScale<Outer, Inner> {
+  /** Position (start) of the inner band within `outer`. */
+  (outer: Outer, inner: Inner): number;
+  /** Inner bandwidth — the rendered width of one inner bar. */
+  bandwidth(): number;
+  /** Inner step — distance between adjacent inner band starts. */
+  step(): number;
+  /** Outer band scale this is nested inside. */
+  readonly outer: BandScale<Outer>;
+  /** Ordered keys of the inner band scale. */
+  readonly innerKeys: readonly Inner[];
+}
+
+export interface GroupedBandScaleOptions {
+  padding?: number;
+  paddingInner?: number;
+  paddingOuter?: number;
+  align?: number;
+}
+
+/**
+ * Build a nested band scale: each band of the `outer` scale is subdivided
+ * into one inner band per key. Returns a function `(outerKey, innerKey) →
+ * position` plus inner `bandwidth()` and `step()`.
+ *
+ * Use this for grouped bars / dot plots where each category has multiple
+ * series side by side. Outer scale handles category placement and
+ * spacing; inner band controls intra-group layout.
+ */
+export function groupedBandScale<Outer, Inner>(
+  outer: BandScale<Outer>,
+  innerKeys: readonly Inner[],
+  options: GroupedBandScaleOptions = {},
+): GroupedBandScale<Outer, Inner> {
+  const inner = bandScale(innerKeys, [0, outer.bandwidth()], options);
+
+  const grouped = ((outerValue: Outer, innerValue: Inner) => {
+    const outerStart = outer(outerValue);
+    if (Number.isNaN(outerStart)) return Number.NaN;
+    const innerPos = inner(innerValue);
+    if (Number.isNaN(innerPos)) return Number.NaN;
+    return outerStart + innerPos;
+  }) as GroupedBandScale<Outer, Inner>;
+
+  Object.defineProperties(grouped, {
+    outer: { value: outer, enumerable: true },
+    innerKeys: { value: [...innerKeys], enumerable: true },
+  });
+
+  grouped.bandwidth = () => inner.bandwidth();
+  grouped.step = () => inner.step();
+
+  return grouped;
+}