insomni-plot 0.1.0-alpha.0

package/src/colorbar.d.ts

@@ -0,0 +1,69 @@
+import { type BlendSpace, type Color, type GlyphAtlas, type Group } from "insomni";
+import type { ContinuousPalette } from "./colors.ts";
+import type { LegendBuilder } from "./legend.ts";
+export type ColorBarOrientation = "vertical" | "horizontal";
+export type ColorBarLabelSide = "auto" | "before" | "after";
+export interface ColorBarOptions {
+    /** Continuous palette to sample. */
+    palette: ContinuousPalette;
+    /** Numeric domain mapped onto the bar. */
+    domain: readonly [number, number];
+    /** Default `"vertical"` (chart-right placement). */
+    orientation?: ColorBarOrientation;
+    /** Long-axis length in pixels. Default `120`. */
+    length?: number;
+    /** Short-axis thickness in pixels. Default `12`. */
+    thickness?: number;
+    /** Number of palette stops sampled into rects. Default `64`. */
+    steps?: number;
+    /** Tick count target. Default `5`. */
+    ticks?: number;
+    /** Optional explicit tick values (override `ticks`). */
+    tickValues?: readonly number[];
+    /**
+     * Minor ticks between majors — number `N` subdivides each major interval
+     * into `N` parts (so `N=2` puts one minor halfway between adjacent majors).
+     * Pass an explicit array to place minor ticks at specific values.
+     */
+    minorTicks?: number | readonly number[];
+    /** Length of minor tick marks. Default `tickSize / 2` from the axis. */
+    minorTickSize?: number;
+    /**
+     * Render a tick label only every `N`th major tick. Default `1`. Use `2`
+     * to label every other major, etc. The unlabeled ticks still draw.
+     */
+    labelStep?: number;
+    /** Tick label formatter. Default uses the underlying linear-scale formatter. */
+    format?: (v: number) => string;
+    /**
+     * Where to draw the tick labels relative to the bar.
+     * - `"after"` (default): right of vertical / below horizontal — the
+     *   conventional placement next to a chart's outer edge.
+     * - `"before"`: left of vertical / above horizontal.
+     */
+    labelSide?: ColorBarLabelSide;
+    /** Optional axis title (typically the color channel's name). */
+    title?: string;
+    /** Atlas required to render labels/title. Without it the bar is unlabeled. */
+    atlas?: GlyphAtlas;
+    fontSize?: number;
+    labelColor?: Color;
+    titleFontSize?: number;
+    titleColor?: Color;
+    /** Optional outline around the bar rectangle. */
+    stroke?: Color;
+    strokeWidth?: number;
+    group?: Group;
+    /**
+     * Override the color space used to interpolate the palette stops into
+     * the bar's gradient. Falls back to the palette's own `blendSpace`
+     * (which the chart pipeline normally sets from `theme.paletteBlendSpace`,
+     * default `"oklch"`).
+     */
+    blendSpace?: BlendSpace;
+}
+/**
+ * Continuous color bar. Returned shape matches `LegendBuilder` so it slots
+ * into the same chart-pipeline legend anchor as the categorical legend().
+ */
+export declare function colorBar(options: ColorBarOptions): LegendBuilder;

package/src/colorbar.ts

@@ -0,0 +1,294 @@
+// ---------------------------------------------------------------------------
+// Continuous color-bar legend
+// ---------------------------------------------------------------------------
+// Mirrors the categorical `legend()` shape (`LegendBuilder`) so the chart
+// pipeline can place either kind into the same legend slot. The bar samples
+// a continuous palette across `domain`, paints it as N stacked rects (so
+// SVG export stays vector-friendly without an embedded raster), and draws
+// ticks/labels via `bottomAxis` / `leftAxis` against a `linearScale`.
+
+import {
+  BLACK,
+  type BlendSpace,
+  type Color,
+  type GlyphAtlas,
+  type Group,
+  type Layer,
+} from "insomni";
+import { bottomAxis, leftAxis, rightAxis, topAxis } from "./axis.ts";
+import type { ContinuousPalette } from "./colors.ts";
+import { pad, placeable, stack, type Placeable } from "./layout/box.ts";
+import type { LegendBuilder } from "./legend.ts";
+import { linearScale } from "./scales.ts";
+
+export type ColorBarOrientation = "vertical" | "horizontal";
+export type ColorBarLabelSide = "auto" | "before" | "after";
+
+export interface ColorBarOptions {
+  /** Continuous palette to sample. */
+  palette: ContinuousPalette;
+  /** Numeric domain mapped onto the bar. */
+  domain: readonly [number, number];
+  /** Default `"vertical"` (chart-right placement). */
+  orientation?: ColorBarOrientation;
+  /** Long-axis length in pixels. Default `120`. */
+  length?: number;
+  /** Short-axis thickness in pixels. Default `12`. */
+  thickness?: number;
+  /** Number of palette stops sampled into rects. Default `64`. */
+  steps?: number;
+  /** Tick count target. Default `5`. */
+  ticks?: number;
+  /** Optional explicit tick values (override `ticks`). */
+  tickValues?: readonly number[];
+  /**
+   * Minor ticks between majors — number `N` subdivides each major interval
+   * into `N` parts (so `N=2` puts one minor halfway between adjacent majors).
+   * Pass an explicit array to place minor ticks at specific values.
+   */
+  minorTicks?: number | readonly number[];
+  /** Length of minor tick marks. Default `tickSize / 2` from the axis. */
+  minorTickSize?: number;
+  /**
+   * Render a tick label only every `N`th major tick. Default `1`. Use `2`
+   * to label every other major, etc. The unlabeled ticks still draw.
+   */
+  labelStep?: number;
+  /** Tick label formatter. Default uses the underlying linear-scale formatter. */
+  format?: (v: number) => string;
+  /**
+   * Where to draw the tick labels relative to the bar.
+   * - `"after"` (default): right of vertical / below horizontal — the
+   *   conventional placement next to a chart's outer edge.
+   * - `"before"`: left of vertical / above horizontal.
+   */
+  labelSide?: ColorBarLabelSide;
+  /** Optional axis title (typically the color channel's name). */
+  title?: string;
+  /** Atlas required to render labels/title. Without it the bar is unlabeled. */
+  atlas?: GlyphAtlas;
+  fontSize?: number;
+  labelColor?: Color;
+  titleFontSize?: number;
+  titleColor?: Color;
+  /** Optional outline around the bar rectangle. */
+  stroke?: Color;
+  strokeWidth?: number;
+  group?: Group;
+  /**
+   * Override the color space used to interpolate the palette stops into
+   * the bar's gradient. Falls back to the palette's own `blendSpace`
+   * (which the chart pipeline normally sets from `theme.paletteBlendSpace`,
+   * default `"oklch"`).
+   */
+  blendSpace?: BlendSpace;
+}
+
+const DEFAULT_LENGTH = 120;
+const DEFAULT_THICKNESS = 12;
+const DEFAULT_STEPS = 64;
+const DEFAULT_TICKS = 5;
+
+/**
+ * Continuous color bar. Returned shape matches `LegendBuilder` so it slots
+ * into the same chart-pipeline legend anchor as the categorical legend().
+ */
+export function colorBar(options: ColorBarOptions): LegendBuilder {
+  const palette =
+    options.blendSpace && options.palette.blendSpace !== options.blendSpace
+      ? options.palette.withBlendSpace(options.blendSpace)
+      : options.palette;
+  const orientation: ColorBarOrientation = options.orientation ?? "vertical";
+  const length = options.length ?? DEFAULT_LENGTH;
+  const thickness = options.thickness ?? DEFAULT_THICKNESS;
+  const steps = Math.max(2, options.steps ?? DEFAULT_STEPS);
+  const fontSize = options.fontSize ?? 11;
+  const labelColor = options.labelColor ?? BLACK;
+  const titleFontSize = options.titleFontSize ?? fontSize;
+  const titleColor = options.titleColor ?? labelColor;
+  const labelSide: ColorBarLabelSide = options.labelSide ?? "auto";
+  const atlas = options.atlas;
+  const title = options.title && options.title.length > 0 ? options.title : undefined;
+
+  // Resolve which side of the bar the tick labels go on.
+  // "auto" defaults to "after" on both axes.
+  const before = labelSide === "before";
+
+  // Underlying tick scale: linear over the bar's pixel length.
+  // For vertical bars we want the domain max at the *top*, so we map
+  // domain → [length, 0] (low end at the bottom of the bar).
+  const tickScale =
+    orientation === "vertical"
+      ? linearScale(options.domain, [length, 0])
+      : linearScale(options.domain, [0, length]);
+
+  // Axis builder (without title — title is rendered as a sibling Placeable
+  // below so its width is honestly accounted for in the bbox).
+  const axisOptions = {
+    atlas,
+    ticks: options.ticks ?? DEFAULT_TICKS,
+    tickValues: options.tickValues,
+    minorTicks: options.minorTicks,
+    minorTickSize: options.minorTickSize,
+    labelStep: options.labelStep,
+    format: options.format,
+    labelFontSize: fontSize,
+    labelColor,
+    tickColor: labelColor,
+    axisLineColor: labelColor,
+    gridLines: false,
+  } as const;
+
+  const axisBuilder =
+    orientation === "vertical"
+      ? before
+        ? leftAxis(tickScale, axisOptions)
+        : rightAxis(tickScale, axisOptions)
+      : before
+        ? topAxis(tickScale, axisOptions)
+        : bottomAxis(tickScale, axisOptions);
+
+  const measurement = axisBuilder.measure(atlas);
+  const labelOverhead = measurement.thickness;
+
+  // Bar+axis Placeable: the bar rectangle plus its tick axis. No title.
+  const barWidth = orientation === "vertical" ? thickness + labelOverhead : length;
+  const barHeight = orientation === "vertical" ? length : thickness + labelOverhead;
+
+  const isVertical = orientation === "vertical";
+
+  const barWithAxis: Placeable = placeable({ width: barWidth, height: barHeight }, (layer, o) => {
+    // Inner top-left of the bar rectangle within this Placeable. The axis
+    // labels live on whichever side `before` selects, so the bar is offset
+    // by labelOverhead along the *thickness* axis only.
+    const barX = isVertical && before ? o.x + labelOverhead : o.x;
+    const barY = !isVertical && before ? o.y + labelOverhead : o.y;
+
+    paintBar({
+      layer,
+      x: barX,
+      y: barY,
+      orientation,
+      length,
+      thickness,
+      steps,
+      palette,
+      group: options.group,
+    });
+
+    if (options.stroke) {
+      layer.pushRect({
+        x: barX,
+        y: barY,
+        width: isVertical ? thickness : length,
+        height: isVertical ? length : thickness,
+        stroke: options.stroke,
+        strokeWidth: options.strokeWidth ?? 1,
+        group: options.group,
+      });
+    }
+
+    // Axis hugs the bar's far edge along the thickness axis when `!before`.
+    const axisOrigin = {
+      x: isVertical && !before ? barX + thickness : barX,
+      y: !isVertical && !before ? barY + thickness : barY,
+    };
+    axisBuilder.addTo(layer, axisOrigin);
+  });
+
+  // The endpoint tick labels are vertically (or horizontally for horizontal
+  // bars) centered on the bar's first/last tick — so they extend `fontSize/2`
+  // axially past the bar's length on both ends. Pad the bar Placeable so the
+  // bbox includes that overflow; otherwise the top label crashes into a
+  // title stacked above (or into the plot below).
+  const labelHalf = fontSize / 2;
+  const paddedBarWithAxis: Placeable =
+    orientation === "vertical"
+      ? pad(barWithAxis, { top: labelHalf, bottom: labelHalf })
+      : pad(barWithAxis, { left: labelHalf, right: labelHalf });
+
+  // Optional title Placeable, stacked above the bar. Width measured against
+  // the atlas so the colorbar's overall bbox includes it — fixing the case
+  // where a wide title (e.g. "value") used to overflow into the plot area.
+  let composed: Placeable = paddedBarWithAxis;
+  if (atlas && title) {
+    const titleWidth = atlas.measureText(title, {
+      fontSize: titleFontSize,
+      simple: true,
+    }).width;
+    const titleBox: Placeable = placeable(
+      { width: titleWidth, height: titleFontSize },
+      (layer, o) => {
+        layer.pushText({
+          simple: true,
+          text: title,
+          x: o.x,
+          // `pushText.y` is the TOP of the text (matches axis.ts label
+          // rendering where `y - fontSize/2` centers on a tick).
+          y: o.y,
+          fontSize: titleFontSize,
+          color: titleColor,
+          align: "left",
+          group: options.group,
+        });
+      },
+    );
+    // Vertical bars: stack title above bar, left-aligned (so the bar stays
+    // flush with the legend slot's left edge — i.e. close to the plot).
+    // Horizontal bars: same vertical stacking; title sits above.
+    const titlePadding = 4;
+    composed = stack([titleBox, paddedBarWithAxis], {
+      direction: "vertical",
+      align: "start",
+      gap: titlePadding,
+    });
+  }
+
+  const totalSize = composed.measure();
+
+  return {
+    length: steps,
+    measure: () => totalSize,
+    getEntryBboxes: () => [],
+    addTo(layer: Layer, origin) {
+      composed.addTo(layer, { x: origin.x, y: origin.y });
+    },
+  };
+}
+
+interface PaintBarArgs {
+  layer: Layer;
+  x: number;
+  y: number;
+  orientation: ColorBarOrientation;
+  length: number;
+  thickness: number;
+  steps: number;
+  palette: ContinuousPalette;
+  group: Group | undefined;
+}
+
+/**
+ * Paint the bar gradient as N stacked rects. SVG export stays vector-only.
+ * Cells are sized with a 0.5px overlap on each side so anti-aliased seams
+ * don't show up against light backgrounds.
+ */
+function paintBar(a: PaintBarArgs): void {
+  const stepLen = a.length / a.steps;
+  const vertical = a.orientation === "vertical";
+  for (let i = 0; i < a.steps; i++) {
+    // For vertical bars the palette runs bottom→top on screen but `t` runs
+    // low→high; flip i so top = max.
+    const tBase = (i + 0.5) / a.steps;
+    const fill = a.palette(vertical ? 1 - tBase : tBase);
+    const offset = i * stepLen;
+    a.layer.pushRect({
+      x: vertical ? a.x : a.x + offset - 0.5,
+      y: vertical ? a.y + offset - 0.5 : a.y,
+      width: vertical ? a.thickness : stepLen + 1,
+      height: vertical ? stepLen + 1 : a.thickness,
+      fill,
+      group: a.group,
+    });
+  }
+}

package/src/colors.d.ts

@@ -0,0 +1,57 @@
+import { type BlendSpace, type Color } from "insomni";
+export interface ContinuousPalette {
+    (t: number): Color;
+    readonly kind: "continuous";
+    readonly stops: readonly Color[];
+    /** Color space used to interpolate between adjacent stops. */
+    readonly blendSpace: BlendSpace;
+    /**
+     * Return a new palette with the same stops but interpolating in the given
+     * space. The original is unchanged. Cheap — palettes are stateless.
+     */
+    withBlendSpace(space: BlendSpace): ContinuousPalette;
+}
+export interface CategoricalPalette {
+    (index: number): Color;
+    readonly kind: "categorical";
+    readonly colors: readonly Color[];
+}
+export declare function colorScale(palette: ContinuousPalette, domain: readonly [number, number]): (value: number) => Color;
+export declare function colorScale<Domain>(palette: CategoricalPalette, domain: readonly Domain[]): (value: Domain) => Color;
+export declare const viridis: ContinuousPalette;
+export declare const plasma: ContinuousPalette;
+export declare const inferno: ContinuousPalette;
+export declare const magma: ContinuousPalette;
+export declare const cividis: ContinuousPalette;
+export declare const coolwarm: ContinuousPalette;
+export declare const rdbu: ContinuousPalette;
+export declare const spectral: ContinuousPalette;
+export declare const tableau10: CategoricalPalette;
+export declare const category10: CategoricalPalette;
+export declare const pastel: CategoricalPalette;
+export declare const set1: CategoricalPalette;
+export declare const set2: CategoricalPalette;
+export declare const set3: CategoricalPalette;
+export declare const dark2: CategoricalPalette;
+export declare const accent: CategoricalPalette;
+export declare const paired: CategoricalPalette;
+export declare const blues: ContinuousPalette;
+export declare const greens: ContinuousPalette;
+export declare const oranges: ContinuousPalette;
+export declare const reds: ContinuousPalette;
+export declare const purples: ContinuousPalette;
+export declare const greys: ContinuousPalette;
+export declare const brbg: ContinuousPalette;
+export declare const prgn: ContinuousPalette;
+export declare const piyg: ContinuousPalette;
+export declare const puor: ContinuousPalette;
+/**
+ * Build a continuous palette from an arbitrary list of CSS hex stops.
+ * Stops are evenly spaced; sample with `palette(t)` where `t ∈ [0, 1]`.
+ */
+export declare function continuousPalette(hexStops: readonly string[]): ContinuousPalette;
+/**
+ * Build a categorical palette from an arbitrary list of CSS hex colors.
+ * Indices wrap modulo length, so `palette(N)` always returns a valid color.
+ */
+export declare function categoricalPalette(hexColors: readonly string[]): CategoricalPalette;

package/src/colors.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "vite-plus/test";
+
+import { category10, colorScale, viridis } from "./colors.ts";
+
+describe("dataviz colors", () => {
+  test("continuous palettes clamp at the ends", () => {
+    expect(viridis(-1)).toEqual(viridis.stops[0]);
+    expect(viridis(2)).toEqual(viridis.stops[viridis.stops.length - 1]);
+  });
+
+  test("categorical palettes wrap indices", () => {
+    expect(category10(10)).toEqual(category10(0));
+    expect(category10(-1)).toEqual(category10(category10.colors.length - 1));
+  });
+
+  test("colorScale maps numeric domains through continuous palettes", () => {
+    const scale = colorScale(viridis, [0, 10]);
+
+    expect(scale(5)).toEqual(viridis(0.5));
+  });
+
+  test("colorScale maps categorical domains through categorical palettes", () => {
+    const scale = colorScale(category10, ["cpu", "memory", "network"]);
+
+    expect(scale("memory")).toEqual(category10(1));
+    expect(scale("network")).toEqual(category10(2));
+  });
+});