insomni-plot 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "insomni-plot",
+  "version": "0.1.0-alpha.0",
+  "description": "Plotting and charting for insomni.",
+  "license": "GPL-3.0",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./core": "./dist/core.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "insomni": "0.2.0-alpha.0"
+  },
+  "peerDependencies": {
+    "typegpu": "^0.10.2"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "test:browser": "vp test -c vite.browser-test.config.ts",
+    "check": "vp check"
+  }
+}

package/src/annotations.d.ts

@@ -0,0 +1,121 @@
+import { type Color, type GlyphAtlas, type Group } from "insomni";
+import { type Accessor, type MarkBuilder, type ValueOrAccessor } from "./marks.ts";
+export type RuleAnchor = "start" | "middle" | "end";
+interface RuleStyle {
+    stroke?: Color;
+    strokeWidth?: number;
+    dashPattern?: readonly number[];
+    dashOffset?: number;
+}
+interface RuleLabel {
+    label?: string;
+    /** Where the label sits along the rule. Default `"end"`. */
+    labelAnchor?: RuleAnchor;
+    /** Perpendicular offset from the rule (positive = away from the data). Default `6`. */
+    labelOffset?: number;
+    /** Tangential offset from the chosen anchor (positive = inwards). Default `6`. */
+    labelInset?: number;
+    labelColor?: Color;
+    fontSize?: number;
+    fontStyle?: string;
+}
+export interface HorizontalRuleOptions extends RuleStyle, RuleLabel {
+    /** Value (in layer-space pixels, post-scale) of the horizontal rule. */
+    y: number;
+    x?: never;
+    /** Range of x covered. Required — typically `[0, plot.width]`. */
+    extent: readonly [number, number];
+    group?: Group;
+}
+export interface VerticalRuleOptions extends RuleStyle, RuleLabel {
+    /** Value (in layer-space pixels, post-scale) of the vertical rule. */
+    x: number;
+    y?: never;
+    /** Range of y covered. Required — typically `[0, plot.height]`. */
+    extent: readonly [number, number];
+    group?: Group;
+}
+export type RuleMarkOptions = HorizontalRuleOptions | VerticalRuleOptions;
+export declare function ruleMark(options: RuleMarkOptions): MarkBuilder;
+interface BandStyle {
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    /** Draw the two perpendicular edge lines (uses `stroke`). Default `true` when `stroke` set. */
+    edges?: boolean;
+}
+interface BandLabel {
+    label?: string;
+    /** Where the label sits along the band. Default `"middle"`. */
+    labelAnchor?: RuleAnchor;
+    /** Perpendicular offset into the perpendicular extent (positive = inwards). Default `4`. */
+    labelOffset?: number;
+    labelColor?: Color;
+    fontSize?: number;
+    fontStyle?: string;
+}
+export interface VerticalBandOptions extends BandStyle, BandLabel {
+    /** Range along the x axis (vertical band — fills between x0 and x1). */
+    x: readonly [number, number];
+    y?: never;
+    /** Required perpendicular extent (typically `[0, plot.height]`). */
+    extent: readonly [number, number];
+    group?: Group;
+}
+export interface HorizontalBandOptions extends BandStyle, BandLabel {
+    /** Range along the y axis (horizontal band). */
+    y: readonly [number, number];
+    x?: never;
+    /** Required perpendicular extent (typically `[0, plot.width]`). */
+    extent: readonly [number, number];
+    group?: Group;
+}
+export type BandMarkOptions = VerticalBandOptions | HorizontalBandOptions;
+export declare function bandMark(options: BandMarkOptions): MarkBuilder;
+export type ValueLabelAlign = "left" | "center" | "right";
+/**
+ * Optional rounded-rectangle background drawn behind label text. When set
+ * (and an `atlas` is available for measurement), `valueLabelMark` measures
+ * each label and emits a `pushRect` underneath sized to the text bounds plus
+ * `padding`. The rect's anchor matches the label's `align` so the text stays
+ * visually centered on `(x, y) + offset`.
+ */
+export interface LabelBoxStyle {
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    /** Pixels added on each side. Number = uniform; object = per-edge. Default `4`. */
+    padding?: number | {
+        x?: number;
+        y?: number;
+    };
+    cornerRadius?: number;
+}
+export interface ValueLabelMarkOptions<T> {
+    x: Accessor<T, number>;
+    y: Accessor<T, number>;
+    text: Accessor<T, string>;
+    /** Horizontal anchor of the text relative to (`x`,`y`). Default `"center"`. */
+    align?: ValueLabelAlign;
+    /** Pixel offset from (`x`,`y`). Default `{ x: 0, y: -4 }` (above). */
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    color?: ValueOrAccessor<T, Color>;
+    fontSize?: number;
+    fontStyle?: string;
+    /** Skip labels for which this returns false. */
+    filter?: Accessor<T, boolean>;
+    /** Optional rounded-rect background. */
+    box?: LabelBoxStyle;
+    /**
+     * Glyph atlas used to measure each label's true rendered width and height
+     * for `box` sizing. When omitted the box falls back to a coarse character-
+     * width estimate that visibly mismatches the glyphs at small font sizes.
+     */
+    atlas?: GlyphAtlas;
+    group?: Group;
+}
+export declare function valueLabelMark<T>(data: readonly T[], options: ValueLabelMarkOptions<T>): MarkBuilder;
+export {};

package/src/annotations.ts

@@ -0,0 +1,438 @@
+import { BLACK, type Color, type GlyphAtlas, type Group, type Layer } from "insomni";
+import {
+  resolveValueOrAccessor as resolve,
+  type Accessor,
+  type MarkBuilder,
+  type MarkOrigin,
+  type ValueOrAccessor,
+} from "./marks.ts";
+import { TEXT_WIDTH_FALLBACK_RATIO } from "./format.ts";
+
+// ---------------------------------------------------------------------------
+// ruleMark — horizontal or vertical reference line, optionally labelled
+// ---------------------------------------------------------------------------
+
+export type RuleAnchor = "start" | "middle" | "end";
+
+interface RuleStyle {
+  stroke?: Color;
+  strokeWidth?: number;
+  dashPattern?: readonly number[];
+  dashOffset?: number;
+}
+
+interface RuleLabel {
+  label?: string;
+  /** Where the label sits along the rule. Default `"end"`. */
+  labelAnchor?: RuleAnchor;
+  /** Perpendicular offset from the rule (positive = away from the data). Default `6`. */
+  labelOffset?: number;
+  /** Tangential offset from the chosen anchor (positive = inwards). Default `6`. */
+  labelInset?: number;
+  labelColor?: Color;
+  fontSize?: number;
+  fontStyle?: string;
+}
+
+export interface HorizontalRuleOptions extends RuleStyle, RuleLabel {
+  /** Value (in layer-space pixels, post-scale) of the horizontal rule. */
+  y: number;
+  x?: never;
+  /** Range of x covered. Required — typically `[0, plot.width]`. */
+  extent: readonly [number, number];
+  group?: Group;
+}
+
+export interface VerticalRuleOptions extends RuleStyle, RuleLabel {
+  /** Value (in layer-space pixels, post-scale) of the vertical rule. */
+  x: number;
+  y?: never;
+  /** Range of y covered. Required — typically `[0, plot.height]`. */
+  extent: readonly [number, number];
+  group?: Group;
+}
+
+export type RuleMarkOptions = HorizontalRuleOptions | VerticalRuleOptions;
+
+function isHorizontalRule(opts: RuleMarkOptions): opts is HorizontalRuleOptions {
+  return typeof (opts as HorizontalRuleOptions).y === "number";
+}
+
+export function ruleMark(options: RuleMarkOptions): MarkBuilder {
+  return {
+    length: 1,
+    addTo(layer: Layer, origin: MarkOrigin = {}) {
+      const ox = origin.x ?? 0;
+      const oy = origin.y ?? 0;
+      const stroke = options.stroke ?? BLACK;
+      const width = options.strokeWidth ?? 1;
+      const [e0, e1] = options.extent;
+
+      const horizontal = isHorizontalRule(options);
+      const x1 = horizontal ? ox + e0 : ox + options.x;
+      const y1 = horizontal ? oy + options.y : oy + e0;
+      const x2 = horizontal ? ox + e1 : ox + options.x;
+      const y2 = horizontal ? oy + options.y : oy + e1;
+
+      if (options.dashPattern && options.dashPattern.length > 0) {
+        layer.pushPolyline({
+          points: [
+            { x: x1, y: y1 },
+            { x: x2, y: y2 },
+          ],
+          color: stroke,
+          width,
+          dashPattern: options.dashPattern,
+          dashOffset: options.dashOffset,
+          group: options.group,
+        });
+      } else {
+        layer.pushLine({ x1, y1, x2, y2, color: stroke, width, group: options.group });
+      }
+
+      if (options.label) {
+        const fontSize = options.fontSize ?? 11;
+        const labelOffset = options.labelOffset ?? 6;
+        const labelInset = options.labelInset ?? 6;
+        const anchor: RuleAnchor = options.labelAnchor ?? "end";
+        const labelColor = options.labelColor ?? stroke;
+        const e0o = horizontal ? ox + e0 : oy + e0;
+        const e1o = horizontal ? ox + e1 : oy + e1;
+        const along =
+          anchor === "start"
+            ? Math.min(e0o, e1o) + labelInset
+            : anchor === "middle"
+              ? (e0o + e1o) / 2
+              : Math.max(e0o, e1o) - labelInset;
+        const align = anchor === "start" ? "left" : anchor === "middle" ? "center" : "right";
+
+        if (layer.atlas != null) {
+          if (horizontal) {
+            layer.pushText({
+              simple: true,
+              text: options.label,
+              x: along,
+              y: oy + options.y - labelOffset - fontSize,
+              fontSize,
+              color: labelColor,
+              align,
+              group: options.group,
+            });
+          } else {
+            layer.pushText({
+              simple: true,
+              text: options.label,
+              x: ox + options.x + labelOffset,
+              y: along,
+              fontSize,
+              color: labelColor,
+              align: "left",
+              group: options.group,
+            });
+          }
+        }
+      }
+
+      return layer;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// bandMark — highlighted x or y range, with optional label
+// ---------------------------------------------------------------------------
+
+interface BandStyle {
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Draw the two perpendicular edge lines (uses `stroke`). Default `true` when `stroke` set. */
+  edges?: boolean;
+}
+
+interface BandLabel {
+  label?: string;
+  /** Where the label sits along the band. Default `"middle"`. */
+  labelAnchor?: RuleAnchor;
+  /** Perpendicular offset into the perpendicular extent (positive = inwards). Default `4`. */
+  labelOffset?: number;
+  labelColor?: Color;
+  fontSize?: number;
+  fontStyle?: string;
+}
+
+export interface VerticalBandOptions extends BandStyle, BandLabel {
+  /** Range along the x axis (vertical band — fills between x0 and x1). */
+  x: readonly [number, number];
+  y?: never;
+  /** Required perpendicular extent (typically `[0, plot.height]`). */
+  extent: readonly [number, number];
+  group?: Group;
+}
+
+export interface HorizontalBandOptions extends BandStyle, BandLabel {
+  /** Range along the y axis (horizontal band). */
+  y: readonly [number, number];
+  x?: never;
+  /** Required perpendicular extent (typically `[0, plot.width]`). */
+  extent: readonly [number, number];
+  group?: Group;
+}
+
+export type BandMarkOptions = VerticalBandOptions | HorizontalBandOptions;
+
+function isVerticalBand(opts: BandMarkOptions): opts is VerticalBandOptions {
+  return Array.isArray((opts as VerticalBandOptions).x);
+}
+
+export function bandMark(options: BandMarkOptions): MarkBuilder {
+  return {
+    length: 1,
+    addTo(layer: Layer, origin: MarkOrigin = {}) {
+      const ox = origin.x ?? 0;
+      const oy = origin.y ?? 0;
+      const [eA, eB] = options.extent;
+      const vertical = isVerticalBand(options);
+      const [pA, pB] = vertical ? options.x : options.y;
+      const xMin = vertical ? ox + Math.min(pA, pB) : ox + Math.min(eA, eB);
+      const yMin = vertical ? oy + Math.min(eA, eB) : oy + Math.min(pA, pB);
+      const xW = vertical ? Math.abs(pB - pA) : Math.abs(eB - eA);
+      const yH = vertical ? Math.abs(eB - eA) : Math.abs(pB - pA);
+
+      if (options.fill) {
+        layer.pushRect({
+          x: xMin,
+          y: yMin,
+          width: xW,
+          height: yH,
+          fill: options.fill,
+          group: options.group,
+        });
+      }
+
+      if (options.stroke && (options.edges ?? true)) {
+        const sw = options.strokeWidth ?? 1;
+        if (vertical) {
+          layer.pushLine({
+            x1: ox + pA,
+            y1: yMin,
+            x2: ox + pA,
+            y2: yMin + yH,
+            color: options.stroke,
+            width: sw,
+            group: options.group,
+          });
+          layer.pushLine({
+            x1: ox + pB,
+            y1: yMin,
+            x2: ox + pB,
+            y2: yMin + yH,
+            color: options.stroke,
+            width: sw,
+            group: options.group,
+          });
+        } else {
+          layer.pushLine({
+            x1: xMin,
+            y1: oy + pA,
+            x2: xMin + xW,
+            y2: oy + pA,
+            color: options.stroke,
+            width: sw,
+            group: options.group,
+          });
+          layer.pushLine({
+            x1: xMin,
+            y1: oy + pB,
+            x2: xMin + xW,
+            y2: oy + pB,
+            color: options.stroke,
+            width: sw,
+            group: options.group,
+          });
+        }
+      }
+
+      if (options.label) {
+        const fontSize = options.fontSize ?? 10;
+        const labelOffset = options.labelOffset ?? 4;
+        const anchor: RuleAnchor = options.labelAnchor ?? "middle";
+        const labelColor = options.labelColor ?? options.stroke ?? BLACK;
+        const along0 = vertical ? ox + pA : oy + pA;
+        const along1 = vertical ? ox + pB : oy + pB;
+        const center =
+          anchor === "start"
+            ? Math.min(along0, along1)
+            : anchor === "middle"
+              ? (along0 + along1) / 2
+              : Math.max(along0, along1);
+
+        if (layer.atlas != null) {
+          if (vertical) {
+            layer.pushText({
+              simple: true,
+              text: options.label,
+              x: center,
+              y: yMin + labelOffset,
+              fontSize,
+              color: labelColor,
+              align: "center",
+              group: options.group,
+            });
+          } else {
+            layer.pushText({
+              simple: true,
+              text: options.label,
+              x: xMin + labelOffset,
+              y: center - fontSize / 2,
+              fontSize,
+              color: labelColor,
+              align: "left",
+              group: options.group,
+            });
+          }
+        }
+      }
+
+      return layer;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// valueLabelMark — text labels per datum (above/right of bars, beside points)
+// ---------------------------------------------------------------------------
+
+export type ValueLabelAlign = "left" | "center" | "right";
+
+/**
+ * Optional rounded-rectangle background drawn behind label text. When set
+ * (and an `atlas` is available for measurement), `valueLabelMark` measures
+ * each label and emits a `pushRect` underneath sized to the text bounds plus
+ * `padding`. The rect's anchor matches the label's `align` so the text stays
+ * visually centered on `(x, y) + offset`.
+ */
+export interface LabelBoxStyle {
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Pixels added on each side. Number = uniform; object = per-edge. Default `4`. */
+  padding?: number | { x?: number; y?: number };
+  cornerRadius?: number;
+}
+
+export interface ValueLabelMarkOptions<T> {
+  x: Accessor<T, number>;
+  y: Accessor<T, number>;
+  text: Accessor<T, string>;
+  /** Horizontal anchor of the text relative to (`x`,`y`). Default `"center"`. */
+  align?: ValueLabelAlign;
+  /** Pixel offset from (`x`,`y`). Default `{ x: 0, y: -4 }` (above). */
+  offset?: { x?: number; y?: number };
+  color?: ValueOrAccessor<T, Color>;
+  fontSize?: number;
+  fontStyle?: string;
+  /** Skip labels for which this returns false. */
+  filter?: Accessor<T, boolean>;
+  /** Optional rounded-rect background. */
+  box?: LabelBoxStyle;
+  /**
+   * Glyph atlas used to measure each label's true rendered width and height
+   * for `box` sizing. When omitted the box falls back to a coarse character-
+   * width estimate that visibly mismatches the glyphs at small font sizes.
+   */
+  atlas?: GlyphAtlas;
+  group?: Group;
+}
+
+export function valueLabelMark<T>(
+  data: readonly T[],
+  options: ValueLabelMarkOptions<T>,
+): MarkBuilder {
+  return {
+    length: data.length,
+    addTo(layer: Layer, origin: MarkOrigin = {}) {
+      const ox = origin.x ?? 0;
+      const oy = origin.y ?? 0;
+      const align = options.align ?? "center";
+      const offsetX = options.offset?.x ?? 0;
+      const offsetY = options.offset?.y ?? -4;
+      const fontSize = options.fontSize ?? 11;
+      const box = options.box;
+      const padX = box ? boxPad(box.padding, "x") : 0;
+      const padY = box ? boxPad(box.padding, "y") : 0;
+
+      // valueLabelMark is text-only (optional box background + label). Both
+      // pushString and pushText require a glyph atlas; skip the entire mark
+      // when none is present (e.g. SVG export without an external atlas).
+      if (layer.atlas == null) return layer;
+
+      for (let i = 0; i < data.length; i++) {
+        const datum = data[i]!;
+        if (options.filter && !options.filter(datum, i)) continue;
+        const x = ox + options.x(datum, i) + offsetX;
+        const y = oy + options.y(datum, i) + offsetY;
+        const text = options.text(datum, i);
+        const color = options.color === undefined ? BLACK : resolve(options.color, datum, i);
+
+        if (box) {
+          // Prefer real glyph metrics when an atlas is available — the
+          // ratio-based fallback ignores per-glyph advance and visibly
+          // under/over-shoots for short labels.
+          let tw: number;
+          let th: number;
+          if (options.atlas) {
+            const m = options.atlas.measureText(text, { fontSize, simple: true });
+            tw = m.width;
+            th = m.height;
+          } else {
+            tw = text.length * fontSize * TEXT_WIDTH_FALLBACK_RATIO;
+            th = fontSize;
+          }
+          const rx =
+            align === "center" ? x - tw / 2 - padX : align === "right" ? x - tw - padX : x - padX;
+          const ry = y - padY;
+          layer.pushRect({
+            x: rx,
+            y: ry,
+            width: tw + padX * 2,
+            height: th + padY * 2,
+            fill: box.fill,
+            stroke: box.stroke,
+            strokeWidth: box.strokeWidth,
+            cornerRadius: box.cornerRadius,
+            group: options.group,
+          });
+        }
+
+        // Fast path: when the layer has a glyph atlas (v3: layer.atlas) and the
+        // caller hasn't requested any feature outside the fast path's support
+        // (no outline, shadow, gradient, wrap), route through the GPU expansion
+        // pipeline. valueLabelMark itself never sets those, so this is always
+        // safe here. v3 replaced the v1 `stringPack` sentinel with `atlas`:
+        // pushString calls _requireAtlas and throws without one, so checking
+        // atlas != null is the correct gate. When no atlas is present (e.g.
+        // SVG export without an external atlas), skip text emission entirely —
+        // pushText also throws without an atlas.
+        if (layer.atlas != null) {
+          layer.pushString({
+            text,
+            x,
+            y,
+            fontSize,
+            color,
+            align,
+            group: options.group,
+          });
+        }
+      }
+      return layer;
+    },
+  };
+}
+
+function boxPad(padding: LabelBoxStyle["padding"], axis: "x" | "y"): number {
+  if (padding === undefined) return 4;
+  if (typeof padding === "number") return padding;
+  return padding[axis] ?? 4;
+}