insomni-plot 0.1.0-alpha.0

package/src/grammar/scales.ts

@@ -0,0 +1,800 @@
+// ---------------------------------------------------------------------------
+// Auto-scale inference
+// ---------------------------------------------------------------------------
+// Given resolved aesthetics + raw data + a channel role, return a scale that
+// the geom can call as `scale(value) -> pixel/visual`. Domain is computed
+// from the data (or from explicit override). Type is picked from data type.
+
+import type { Color } from "insomni";
+import {
+  bandScale,
+  linearScale,
+  logScale,
+  numericTicks,
+  sqrtScale,
+  timeScale,
+  type BandScale,
+  type ContinuousScale,
+  type NumericDomain,
+  type NumericRange,
+  type TimeScale,
+} from "../scales.ts";
+import { colorScale, type CategoricalPalette, type ContinuousPalette } from "../colors.ts";
+import { quantile } from "../stats/index.ts";
+import { POINT_SHAPE_PALETTE, type PointBorderStyle, type PointShapeKind } from "../marks.ts";
+import { inferDataType, materialize, type ChannelDataType, type ResolvedAes } from "./aes.ts";
+import type { Theme } from "./theme.ts";
+
+// Re-exported for convenience: `ScaleBundle` now lives in `./geoms/types.ts`
+// but historically was importable from this module (and many tests still do).
+export type { ScaleBundle } from "./geoms/types.ts";
+
+export type Channel =
+  | "x"
+  | "y"
+  | "color"
+  | "size"
+  | "shape"
+  | "alpha"
+  | "borderStyle"
+  | "overlayGlyph";
+
+export type PositionScaleType = "linear" | "log" | "sqrt" | "time" | "band";
+export type ColorScaleType = "categorical" | "continuous" | "diverging";
+
+interface BasePositionScaleOptions {
+  range?: NumericRange;
+  nice?: boolean;
+  padding?: number;
+}
+
+/**
+ * `"nice"` is sugar for the existing `nice: true` flag — set as the domain
+ * shortcut so consumers don't need a second toggle when the only reason to
+ * touch `domain` was to pad it to round values. The data extent still
+ * derives the underlying numbers; `"nice"` just toggles the rounding.
+ */
+export type NumericDomainShortcut = "nice";
+
+export interface NumericPositionScaleOptions extends BasePositionScaleOptions {
+  type?: "linear" | "log" | "sqrt";
+  domain?: readonly [number, number] | NumericDomainShortcut;
+}
+
+export interface TimePositionScaleOptions extends BasePositionScaleOptions {
+  type?: "time";
+  domain?: readonly [Date, Date];
+}
+
+export interface BandPositionScaleOptions extends BasePositionScaleOptions {
+  type?: "band";
+  domain?: readonly string[];
+}
+
+export type PositionScaleOptions =
+  | NumericPositionScaleOptions
+  | TimePositionScaleOptions
+  | BandPositionScaleOptions;
+
+export interface CategoricalColorScaleOptions<T> {
+  type?: "categorical";
+  domain?: readonly T[];
+  palette?: CategoricalPalette;
+}
+
+/**
+ * Color-scale domain shortcuts.
+ *
+ * - `"nice"`: alias for the existing `nice: true` flag on continuous color
+ *   scales — pad the data extent to round values.
+ * - `"quantile"`: bucket the data into N quantile bins (default 5). The
+ *   returned scale's `type` becomes `"categorical"` with bucket-label
+ *   domain entries (`"Q1".."QN"`), and the palette is sampled at N evenly
+ *   spaced stops along the chart's continuous palette so the color
+ *   gradient reads as ordinal magnitude rather than nominal category.
+ */
+export type ColorDomainShortcut = "nice" | "quantile";
+
+export interface ContinuousColorScaleOptions {
+  type: "continuous" | "diverging";
+  domain?: readonly [number, number] | ColorDomainShortcut;
+  palette?: ContinuousPalette;
+  /**
+   * Extend the inferred domain outward to "nice" round values (e.g. data
+   * extent `[-2.8, 1.9]` → `[-3, 2]`). Same algorithm position scales use
+   * via `nice: true`. Ignored when `domain` is set explicitly to a tuple.
+   * Equivalent to `domain: "nice"` — keep one form per chart for clarity.
+   */
+  nice?: boolean;
+  /**
+   * Number of quantile buckets to use when `domain: "quantile"`. Default 5
+   * (quintiles). Ignored otherwise.
+   */
+  quantiles?: number;
+  /**
+   * Override the color space used to interpolate the palette stops.
+   * Falls back to `theme.paletteBlendSpace` (default `"oklch"`).
+   */
+  blendSpace?: import("insomni").BlendSpace;
+}
+
+export type ColorScaleOptions<T> = CategoricalColorScaleOptions<T> | ContinuousColorScaleOptions;
+
+export interface SizeScaleOptions {
+  type?: "linear" | "sqrt";
+  domain?: readonly [number, number];
+  range?: readonly [number, number];
+}
+
+export interface AlphaScaleOptions {
+  domain?: readonly [number, number];
+  range?: readonly [number, number];
+}
+
+export interface ShapeScaleOptions {
+  /** Explicit category order (default: order of first appearance). */
+  domain?: readonly unknown[];
+  /** Override the shape palette. Default: `POINT_SHAPE_PALETTE` from `marks`. */
+  palette?: readonly PointShapeKind[];
+}
+
+export interface BorderStyleScaleOptions {
+  /** Explicit category order (default: order of first appearance). */
+  domain?: readonly unknown[];
+  /** Override the border-style palette. Default: `DEFAULT_BORDER_STYLE_PALETTE`. */
+  palette?: readonly PointBorderStyle[];
+}
+
+export interface OverlayGlyphScaleOptions {
+  /** Explicit category order (default: order of first appearance). */
+  domain?: readonly unknown[];
+  /**
+   * Override the overlay palette. Default: a small subset of
+   * `POINT_SHAPE_PALETTE` excluding `circle` so the overlay is visually
+   * distinct from the typical base shape. Use `null` entries to suppress an
+   * overlay for that domain value.
+   */
+  palette?: readonly (PointShapeKind | null)[];
+}
+
+export type ScaleOptions =
+  | PositionScaleOptions
+  | ColorScaleOptions<unknown>
+  | SizeScaleOptions
+  | AlphaScaleOptions
+  | ShapeScaleOptions
+  | BorderStyleScaleOptions
+  | OverlayGlyphScaleOptions;
+
+/** A scale callable: any value → number (or color, for color channels). */
+export type ScaleFn<In, Out> = (value: In) => Out;
+
+export interface PositionScale {
+  readonly kind: "position";
+  readonly type: PositionScaleType;
+  readonly dataType: ChannelDataType;
+  /** Pixel-space transform within the plot frame. */
+  readonly fn: ScaleFn<unknown, number>;
+  /** Underlying scale for axis builders. */
+  readonly axisScale: ContinuousScale | TimeScale | BandScale<string>;
+}
+
+export interface ColorScale {
+  readonly kind: "color";
+  readonly dataType: ChannelDataType;
+  readonly type: ColorScaleType;
+  readonly fn: ScaleFn<unknown, Color>;
+  readonly domain: readonly unknown[];
+  /** Original palette — present for continuous/diverging scales (used by the color-bar legend). */
+  readonly palette?: ContinuousPalette | CategoricalPalette;
+}
+
+export interface SizeScale {
+  readonly kind: "size";
+  readonly fn: ScaleFn<unknown, number>;
+  readonly domain: readonly [number, number];
+  readonly range: readonly [number, number];
+}
+
+export interface AlphaScale {
+  readonly kind: "alpha";
+  readonly fn: ScaleFn<unknown, number>;
+  readonly domain: readonly [number, number];
+  readonly range: readonly [number, number];
+}
+
+export interface ShapeScale {
+  readonly kind: "shape";
+  readonly fn: ScaleFn<unknown, PointShapeKind>;
+  readonly domain: readonly unknown[];
+  readonly palette: readonly PointShapeKind[];
+}
+
+export interface BorderStyleScale {
+  readonly kind: "borderStyle";
+  readonly fn: ScaleFn<unknown, PointBorderStyle>;
+  readonly domain: readonly unknown[];
+  readonly palette: readonly PointBorderStyle[];
+}
+
+export interface OverlayGlyphScale {
+  readonly kind: "overlayGlyph";
+  readonly fn: ScaleFn<unknown, PointShapeKind | null>;
+  readonly domain: readonly unknown[];
+  readonly palette: readonly (PointShapeKind | null)[];
+}
+
+export type ResolvedScale =
+  | PositionScale
+  | ColorScale
+  | SizeScale
+  | AlphaScale
+  | ShapeScale
+  | BorderStyleScale
+  | OverlayGlyphScale;
+
+// ---------------------------------------------------------------------------
+// Domain inference
+// ---------------------------------------------------------------------------
+
+/**
+ * Numeric extent over an arbitrary value array. Non-numeric values are skipped.
+ * Falls back to `[0, 1]` for empty / non-numeric input. Expands a degenerate
+ * single-point domain by ±1 so downstream scales don't divide by zero.
+ */
+export function numericExtent(values: readonly unknown[]): [number, number] {
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const v of values) {
+    if (typeof v !== "number" || !Number.isFinite(v)) continue;
+    if (v < lo) lo = v;
+    if (v > hi) hi = v;
+  }
+  if (!Number.isFinite(lo) || !Number.isFinite(hi)) return [0, 1];
+  if (lo === hi) return [lo - 1, hi + 1];
+  return [lo, hi];
+}
+
+function dateExtent(values: readonly unknown[]): [Date, Date] {
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const v of values) {
+    if (!(v instanceof Date)) continue;
+    const t = v.getTime();
+    if (!Number.isFinite(t)) continue;
+    if (t < lo) lo = t;
+    if (t > hi) hi = t;
+  }
+  if (!Number.isFinite(lo) || !Number.isFinite(hi)) {
+    const now = Date.now();
+    return [new Date(now), new Date(now + 1)];
+  }
+  if (lo === hi) return [new Date(lo - 1), new Date(hi + 1)];
+  return [new Date(lo), new Date(hi)];
+}
+
+// Categorical domain builder. Null / undefined are dropped per the policy in
+// `aes.ts` ("Null / undefined policy for categorical channels") — they do not
+// become a `"null"` category, never throw. Geoms grouping by the same channel
+// should call `dropNullCategoricalIndices` so rendered groups stay aligned
+// with this domain.
+function uniqueStrings(values: readonly unknown[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const v of values) {
+    if (v === null || v === undefined) continue;
+    // oxlint-disable-next-line no-base-to-string -- categorical data can be any scalar; String() is intentional for non-object values after null/undefined filter
+    const s = String(v);
+    if (seen.has(s)) continue;
+    seen.add(s);
+    out.push(s);
+  }
+  return out;
+}
+
+function niceNumeric(domain: [number, number]): [number, number] {
+  const [lo, hi] = domain;
+  if (lo === hi) return [lo - 1, hi + 1];
+  // Snap to a "nice" tick step, then *only* extend outward when the data
+  // overshoots the nearest inner tick by more than half a step. So
+  // [-2.7, 1.9] (step 1) → [-3, 2], but [-2.2, 2.2] stays put — and the
+  // half-step boundary itself (e.g. ±2.5) keeps the original extent.
+  const min = Math.min(lo, hi);
+  const max = Math.max(lo, hi);
+  const ticks = numericTicks(min, max, 5);
+  if (ticks.length < 2) return [lo, hi];
+  const step = Math.abs(ticks[1]! - ticks[0]!);
+  if (!Number.isFinite(step) || step === 0) return [lo, hi];
+  const eps = step * 1e-9;
+  const innerLow = Math.ceil((min - eps) / step) * step; // first tick ≥ min
+  const innerHigh = Math.floor((max + eps) / step) * step; // last tick ≤ max
+  const half = step / 2;
+  const niceMin = innerLow - min > half + eps ? innerLow - step : min;
+  const niceMax = max - innerHigh > half + eps ? innerHigh + step : max;
+  const round = (v: number): number => Number.parseFloat(v.toPrecision(12));
+  return lo <= hi ? [round(niceMin), round(niceMax)] : [round(niceMax), round(niceMin)];
+}
+
+// ---------------------------------------------------------------------------
+// Position scales (x / y)
+// ---------------------------------------------------------------------------
+
+// Pan-zoom reads the user's scale config to seed initial bounds and clamp
+// behavior. Lives here (not in mount.ts) because the parsing rules are
+// scale-shape concerns, not mount-time wiring.
+export function readNumericDomain(
+  scale: PositionScaleOptions | undefined,
+  axis: "x" | "y",
+): readonly [number, number] {
+  const dom = scale?.domain;
+  if (!dom || dom.length !== 2) {
+    throw new Error(
+      `panZoom: ${axis} scale must have an explicit numeric domain (set .scale("${axis}", { type: "linear", domain: [a, b] })).`,
+    );
+  }
+  const [a, b] = dom as readonly [unknown, unknown];
+  const an = a instanceof Date ? a.getTime() : (a as number);
+  const bn = b instanceof Date ? b.getTime() : (b as number);
+  if (
+    typeof an !== "number" ||
+    typeof bn !== "number" ||
+    !Number.isFinite(an) ||
+    !Number.isFinite(bn)
+  ) {
+    throw new Error(
+      `panZoom: ${axis} domain must be a finite [number, number] (got ${JSON.stringify(dom)}).`,
+    );
+  }
+  return [an, bn];
+}
+
+export function readContinuousType(
+  scale: PositionScaleOptions | undefined,
+): "linear" | "log" | "sqrt" {
+  const t = scale?.type;
+  if (t === "log" || t === "sqrt") return t;
+  if (t === "band" || t === "time") {
+    throw new Error(
+      `panZoom: only linear / log / sqrt scales are supported (got "${t}"). Use a continuous numeric domain.`,
+    );
+  }
+  return "linear";
+}
+
+export function buildPositionScale<T>(
+  aes: ResolvedAes<T, unknown>,
+  data: readonly T[],
+  range: NumericRange,
+  options: PositionScaleOptions = {},
+): PositionScale {
+  const values = materialize(aes, data);
+  const dataType = inferDataType(values);
+  const explicitType = options.type;
+  const type: PositionScaleType = explicitType ?? defaultPositionType(dataType);
+
+  // When `type` is omitted the caller's intent is encoded in `options.domain`'s
+  // shape (string[] → band, [Date, Date] → time, [number, number] → numeric).
+  // We've already inferred `type` from the data; trust the explicit domain
+  // when it's present rather than re-narrowing through `options.type`.
+  if (type === "band") {
+    const domain = (options.domain as readonly string[] | undefined) ?? uniqueStrings(values);
+    const scale = bandScale<string>(domain, range, { padding: options.padding ?? 0.1 });
+    const half = scale.bandwidth() / 2;
+    return {
+      kind: "position",
+      type: "band",
+      dataType,
+      axisScale: scale,
+      // Centered within band so points/lines anchor mid-cell.
+      fn: (v: unknown) => scale(String(v)) + half,
+    };
+  }
+
+  if (type === "time" || dataType === "date") {
+    const domain = (options.domain as readonly [Date, Date] | undefined) ?? dateExtent(values);
+    const scale = timeScale(domain, range);
+    return {
+      kind: "position",
+      type: "time",
+      dataType,
+      axisScale: scale,
+      fn: (v: unknown) => scale(v as Date),
+    };
+  }
+
+  // `domain: "nice"` is sugar for the existing `nice: true` flag — apply
+  // the same niceNumeric pass as if the consumer had set both. Tuple
+  // domains still win over the data extent; the `"nice"` string is a
+  // marker that means "use the data extent, then nice it."
+  const rawDomain = options.domain;
+  const isNiceShortcut = rawDomain === "nice";
+  let domain =
+    rawDomain && !isNiceShortcut ? (rawDomain as readonly [number, number]) : numericExtent(values);
+  if (options.nice || isNiceShortcut) domain = niceNumeric([domain[0], domain[1]]);
+
+  let resolvedType: "linear" | "log" | "sqrt" = "linear";
+  let factory: (domain: NumericDomain, range: NumericRange) => ContinuousScale;
+  if (type === "log") {
+    // Log scales require strictly positive (or strictly negative) domains.
+    // When the inferred domain straddles or touches zero we can't return a
+    // valid log scale, so surface the constraint at construction rather
+    // than letting `logScale` throw a less-actionable error downstream.
+    if (domain[0] === 0 || domain[1] === 0 || Math.sign(domain[0]) !== Math.sign(domain[1])) {
+      throw new Error(
+        `Log scale requires a domain with non-zero, same-sign endpoints (got [${domain[0]}, ${domain[1]}]). ` +
+          `Set an explicit positive domain via .scale(channel, { type: "log", domain: [lo, hi] }).`,
+      );
+    }
+    factory = logScale;
+    resolvedType = "log";
+  } else if (type === "sqrt") {
+    factory = sqrtScale;
+    resolvedType = "sqrt";
+  } else {
+    factory = linearScale;
+  }
+  const scale = factory(domain, range);
+  return {
+    kind: "position",
+    type: resolvedType,
+    dataType,
+    axisScale: scale,
+    fn: (v: unknown) => scale(v as number),
+  };
+}
+
+function defaultPositionType(dataType: ChannelDataType): PositionScaleType {
+  if (dataType === "date") return "time";
+  if (dataType === "string" || dataType === "boolean") return "band";
+  return "linear";
+}
+
+// ---------------------------------------------------------------------------
+// Color scale
+// ---------------------------------------------------------------------------
+
+export function buildColorScale<T>(
+  aes: ResolvedAes<T, unknown>,
+  data: readonly T[],
+  theme: Theme,
+  options: ColorScaleOptions<unknown> = {},
+): ColorScale {
+  const values = materialize(aes, data);
+  const dataType = inferDataType(values);
+  const type: ColorScaleType =
+    options.type ?? (dataType === "number" ? "continuous" : "categorical");
+
+  if (type === "categorical") {
+    return buildCategoricalColorScale(uniqueStrings(values), theme, options, dataType);
+  }
+
+  const contOpts =
+    options.type === "continuous" || options.type === "diverging"
+      ? (options as ContinuousColorScaleOptions)
+      : undefined;
+  let palette: ContinuousPalette =
+    contOpts?.palette ??
+    (type === "diverging" ? theme.palettes.diverging : theme.palettes.continuous);
+  const space = contOpts?.blendSpace ?? theme.paletteBlendSpace;
+  if (palette.blendSpace !== space) palette = palette.withBlendSpace(space);
+
+  // Quantile shortcut: collapse the continuous scale to a categorical scale
+  // whose buckets are quantile bins of the data. Palette is sampled at N
+  // evenly spaced stops along the continuous palette so the gradient still
+  // reads as ordinal magnitude (low → high) rather than nominal category.
+  if (contOpts?.domain === "quantile") {
+    return buildQuantileColorScale(values, palette, contOpts, dataType);
+  }
+
+  const isNiceShortcut = contOpts?.domain === "nice";
+  // `domain === "quantile"` already returned above, so by here the only
+  // shortcut left to exclude is `"nice"`; what remains is an explicit tuple.
+  const explicitDomain =
+    contOpts?.domain && contOpts.domain !== "nice"
+      ? (contOpts.domain as readonly [number, number])
+      : undefined;
+  let domain: readonly [number, number] = explicitDomain ?? numericExtent(values);
+  if ((contOpts?.nice || isNiceShortcut) && !explicitDomain) {
+    domain = niceNumeric([domain[0], domain[1]]);
+  }
+  const fn = colorScale(palette, domain);
+  return {
+    kind: "color",
+    type,
+    dataType,
+    domain,
+    fn: (v: unknown) => fn(v as number),
+    palette,
+  };
+}
+
+/**
+ * Build a quantile-bucketed color scale. Data values are sorted, N-1
+ * breakpoints are computed at evenly spaced quantiles (default N=5), and
+ * each input value is mapped to its bucket index via a binary-search-free
+ * sweep (breakpoints are monotonic so a linear scan stays cheap). The
+ * returned scale is shaped as `type: "categorical"` so the rest of the
+ * pipeline (legend, color-bar) treats it as discrete; bucket labels
+ * (`"Q1".."QN"`) live in `domain`.
+ */
+function buildQuantileColorScale(
+  values: readonly unknown[],
+  palette: ContinuousPalette,
+  contOpts: ContinuousColorScaleOptions,
+  dataType: ChannelDataType,
+): ColorScale {
+  const requested = Math.max(1, Math.floor(contOpts.quantiles ?? 5));
+  const numeric: number[] = [];
+  for (const v of values) {
+    if (typeof v === "number" && Number.isFinite(v)) numeric.push(v);
+  }
+  numeric.sort((a, b) => a - b);
+
+  // Internal breakpoints at p = 1/N, 2/N, …, (N-1)/N. Empty array when N=1.
+  // Low-cardinality data can make adjacent quantiles tie (e.g. many values at
+  // the same level), producing duplicate breakpoints. Duplicate or extremal
+  // breakpoints create unreachable buckets: a span between two equal
+  // breakpoints can never be entered, and a breakpoint sitting on the data
+  // min/max leaves the bucket beyond it empty — both skew the palette. Keep
+  // only the *strictly interior* distinct breakpoints (min < bp < max) so D
+  // such breakpoints yield exactly D+1 reachable buckets and palette/labels
+  // match that count.
+  const lo = numeric.length > 0 ? numeric[0]! : 0;
+  const hi = numeric.length > 0 ? numeric[numeric.length - 1]! : 0;
+  const rawBreakpoints: number[] = [];
+  if (numeric.length > 0) {
+    for (let i = 1; i < requested; i++) {
+      rawBreakpoints.push(quantile(numeric, i / requested));
+    }
+  }
+  const breakpoints: number[] = [];
+  for (const bp of rawBreakpoints) {
+    if (bp <= lo || bp >= hi) continue; // drop extremal → empty boundary buckets
+    if (breakpoints.length === 0 || breakpoints[breakpoints.length - 1]! !== bp) {
+      breakpoints.push(bp);
+    }
+  }
+
+  // Reachable buckets = interior breakpoints + 1.
+  const buckets = breakpoints.length + 1;
+
+  // Sample N palette stops at bucket centers (0.5/N, 1.5/N, …, (N-0.5)/N)
+  // — keeps the first/last colors a little inside the palette's extremes,
+  // which tends to read better than hitting the very ends.
+  const bucketColors: Color[] = Array.from({ length: buckets });
+  for (let i = 0; i < buckets; i++) {
+    const t = buckets === 1 ? 0.5 : (i + 0.5) / buckets;
+    bucketColors[i] = palette(t);
+  }
+
+  const domain: readonly string[] = Array.from({ length: buckets }, (_, i) => `Q${i + 1}`);
+
+  return {
+    kind: "color",
+    type: "categorical",
+    dataType,
+    domain,
+    fn: (value: unknown) => {
+      const num = typeof value === "number" ? value : Number(value);
+      if (!Number.isFinite(num)) return bucketColors[0]!;
+      // Linear scan over interior, monotonic breakpoints. Buckets are
+      // left-closed: a value exactly equal to a breakpoint falls into the lower
+      // bucket (`>`), so the data minimum always lands in Q1 and ties resolve to
+      // a single well-defined bucket.
+      let bucket = 0;
+      for (let i = 0; i < breakpoints.length; i++) {
+        if (num > breakpoints[i]!) bucket = i + 1;
+        else break;
+      }
+      return bucketColors[bucket]!;
+    },
+  };
+}
+
+/**
+ * Build a categorical color scale from an explicit key list. Shared between
+ * `buildColorScale` (data-derived domain) and the chart pipeline's implicit
+ * series scale (keys = column names). User-supplied `options.palette` /
+ * `options.domain` win over the inferred values.
+ */
+export function buildCategoricalColorScale(
+  keys: readonly unknown[],
+  theme: Theme,
+  options: ColorScaleOptions<unknown> = {},
+  dataType: ChannelDataType = "string",
+): ColorScale {
+  const catOpts =
+    options.type === "continuous" || options.type === "diverging"
+      ? undefined
+      : (options as CategoricalColorScaleOptions<unknown>);
+  const palette: CategoricalPalette = catOpts?.palette ?? theme.palettes.categorical;
+  const domain: readonly unknown[] = catOpts?.domain ?? keys;
+  const fn = colorScale(palette, domain);
+  return {
+    kind: "color",
+    type: "categorical",
+    dataType,
+    domain,
+    fn: (v: unknown) => fn(v),
+    palette,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Size scale
+// ---------------------------------------------------------------------------
+
+/**
+ * Default range pair for size/alpha when neither the user nor the theme
+ * supplies one. The `buildSizeScale` / `buildAlphaScale` callers pass a theme
+ * override via the chart pipeline; this constant exists so direct callers
+ * (tests, ad-hoc usage) get a sensible default.
+ */
+const defaultSizeRange: readonly [number, number] = [2, 14];
+const defaultAlphaRange: readonly [number, number] = [0.2, 1];
+
+export function buildSizeScale<T>(
+  aes: ResolvedAes<T, number>,
+  data: readonly T[],
+  options: SizeScaleOptions = {},
+): SizeScale {
+  const values = materialize(aes, data);
+  const domain = options.domain ?? numericExtent(values);
+  const range = options.range ?? defaultSizeRange;
+  const type = options.type ?? "sqrt";
+  const factory = type === "sqrt" ? sqrtScale : linearScale;
+  const scale = factory(domain, range);
+  return {
+    kind: "size",
+    fn: (v: unknown) => scale(v as number),
+    domain,
+    range,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Alpha scale
+// ---------------------------------------------------------------------------
+
+export function buildAlphaScale<T>(
+  aes: ResolvedAes<T, number>,
+  data: readonly T[],
+  options: AlphaScaleOptions = {},
+): AlphaScale {
+  const values = materialize(aes, data);
+  const domain = options.domain ?? numericExtent(values);
+  const range = options.range ?? defaultAlphaRange;
+  const scale = linearScale(domain, range);
+  return {
+    kind: "alpha",
+    fn: (v: unknown) => scale(v as number),
+    domain,
+    range,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Shape scale
+// ---------------------------------------------------------------------------
+
+function uniqueValues(values: readonly unknown[]): unknown[] {
+  const seen = new Set<unknown>();
+  const out: unknown[] = [];
+  for (const v of values) {
+    if (v === null || v === undefined) continue;
+    // oxlint-disable-next-line no-base-to-string -- String() only reached for non-object scalars (number, boolean, string) after the typeof guard
+    const key = typeof v === "object" ? v : String(v);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(v);
+  }
+  return out;
+}
+
+export function buildShapeScale<T>(
+  aes: ResolvedAes<T, unknown>,
+  data: readonly T[],
+  options: ShapeScaleOptions = {},
+): ShapeScale {
+  const values = materialize(aes, data);
+  const domain = options.domain ?? uniqueValues(values);
+  const palette = options.palette ?? POINT_SHAPE_PALETTE;
+  const lookup = new Map<unknown, PointShapeKind>();
+  for (let i = 0; i < domain.length; i++) {
+    // oxlint-disable-next-line no-base-to-string -- String() only reached for non-object scalars after the typeof guard
+    const key = typeof domain[i] === "object" ? domain[i] : String(domain[i]);
+    lookup.set(key, palette[i % palette.length]!);
+  }
+  const fallback = palette[0] ?? "circle";
+  return {
+    kind: "shape",
+    domain,
+    palette,
+    fn: (v: unknown) => {
+      // oxlint-disable-next-line no-base-to-string -- String() only reached for non-object scalars after the typeof guard
+      const key = typeof v === "object" ? v : String(v);
+      return lookup.get(key) ?? fallback;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Border-style scale
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_BORDER_STYLE_PALETTE: readonly PointBorderStyle[] = [
+  "solid",
+  "open",
+  "dashed",
+  "dotted",
+];
+
+export function buildBorderStyleScale<T>(
+  aes: ResolvedAes<T, unknown>,
+  data: readonly T[],
+  options: BorderStyleScaleOptions = {},
+): BorderStyleScale {
+  const values = materialize(aes, data);
+  const domain = options.domain ?? uniqueValues(values);
+  const palette = options.palette ?? DEFAULT_BORDER_STYLE_PALETTE;
+  const lookup = new Map<unknown, PointBorderStyle>();
+  for (let i = 0; i < domain.length; i++) {
+    // oxlint-disable-next-line no-base-to-string -- String() only reached for non-object scalars after the typeof guard
+    const key = typeof domain[i] === "object" ? domain[i] : String(domain[i]);
+    lookup.set(key, palette[i % palette.length]!);
+  }
+  const fallback = palette[0] ?? "solid";
+  return {
+    kind: "borderStyle",
+    domain,
+    palette,
+    fn: (v: unknown) => {
+      // oxlint-disable-next-line no-base-to-string -- String() only reached for non-object scalars after the typeof guard
+      const key = typeof v === "object" ? v : String(v);
+      return lookup.get(key) ?? fallback;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Overlay-glyph scale
+// ---------------------------------------------------------------------------
+
+/**
+ * Default overlay palette. First slot is `null` so the most-common category
+ * gets no overlay — overlays are typically a minority styling for flagged /
+ * exceptional rows. The remaining slots are visually distinct glyphs.
+ */
+export const DEFAULT_OVERLAY_GLYPH_PALETTE: readonly (PointShapeKind | null)[] = [
+  null,
+  "plus",
+  "cross",
+  "star",
+  "diamond",
+];
+
+export function buildOverlayGlyphScale<T>(
+  aes: ResolvedAes<T, unknown>,
+  data: readonly T[],
+  options: OverlayGlyphScaleOptions = {},
+): OverlayGlyphScale {
+  const values = materialize(aes, data);
+  const domain = options.domain ?? uniqueValues(values);
+  const palette = options.palette ?? DEFAULT_OVERLAY_GLYPH_PALETTE;
+  const lookup = new Map<unknown, PointShapeKind | null>();
+  for (let i = 0; i < domain.length; i++) {
+    // oxlint-disable-next-line no-base-to-string -- String() only reached for non-object scalars after the typeof guard
+    const key = typeof domain[i] === "object" ? domain[i] : String(domain[i]);
+    lookup.set(key, palette[i % palette.length] ?? null);
+  }
+  return {
+    kind: "overlayGlyph",
+    domain,
+    palette,
+    fn: (v: unknown) => {
+      // oxlint-disable-next-line no-base-to-string -- String() only reached for non-object scalars after the typeof guard
+      const key = typeof v === "object" ? v : String(v);
+      return lookup.has(key) ? (lookup.get(key) ?? null) : null;
+    },
+  };
+}