insomni-plot 0.1.0-alpha.0

package/src/marks/stack.d.ts

@@ -0,0 +1,53 @@
+export interface StackSegment<T, K extends string = string> {
+    /** Original datum the segment came from. */
+    readonly datum: T;
+    /** Key of this segment within the datum (matches `keys[subIndex]`). */
+    readonly key: K;
+    /** Numeric value of this segment. */
+    readonly value: number;
+    /** Cumulative offset — where this segment starts (0 for the first key). */
+    readonly base: number;
+    /** `base + value` — where this segment ends. */
+    readonly top: number;
+    /** Index of this segment within its datum (0-based, same order as `keys`). */
+    readonly subIndex: number;
+    /** Index of the source datum in the input array. */
+    readonly datumIndex: number;
+}
+export type StackOffset = "zero" | "expand" | "silhouette" | "wiggle";
+export type StackOrder = "input" | "ascending" | "descending" | "inside-out" | "appearance";
+export interface StackOptions<T, K extends string = string> {
+    /**
+     * Extract the numeric value for `key` from `datum`. Default: `datum[key]` —
+     * works when the data is a plain object keyed by string.
+     */
+    value?: (datum: T, key: K, datumIndex: number) => number;
+    /**
+     * Baseline offset:
+     * - `"zero"` (default) — bases at 0 going up.
+     * - `"expand"` — normalize each datum to `[0, 1]` (100% stacked).
+     * - `"silhouette"` — center the stack on 0 (`-rowSum/2 .. +rowSum/2`).
+     * - `"wiggle"` — minimize layer wiggle (Byron–Wattenberg streamgraph).
+     */
+    offset?: StackOffset;
+    /**
+     * Series ordering. Reorders the stack from inner-out:
+     * - `"input"` (default) — preserve `keys` order.
+     * - `"ascending"` — smallest total first.
+     * - `"descending"` — largest total first.
+     * - `"inside-out"` — largest in the middle (good for streamgraphs).
+     * - `"appearance"` — by index of each series' max value.
+     */
+    order?: StackOrder;
+}
+/**
+ * Flatten `data` into a list of `StackSegment`s — one per (datum, key) pair —
+ * with cumulative `base` / `top` offsets computed per datum. Supports
+ * `offset` (zero / expand / silhouette / wiggle) and `order` (input /
+ * ascending / descending / inside-out / appearance).
+ *
+ * Output order is `data[0].keys[0], data[0].keys[1], ..., data[1].keys[0],
+ * ...` — convenient for `barMark` / `areaMark`. `subIndex` reflects the
+ * post-`order` stacking position (0 = inner-most).
+ */
+export declare function stack<T, K extends string = string>(data: readonly T[], keys: readonly K[], options?: StackOptions<T, K>): StackSegment<T, K>[];

package/src/marks/stack.ts

@@ -0,0 +1,184 @@
+// ---------------------------------------------------------------------------
+// stack() — data helper for stacked bars / areas
+// ---------------------------------------------------------------------------
+
+export interface StackSegment<T, K extends string = string> {
+  /** Original datum the segment came from. */
+  readonly datum: T;
+  /** Key of this segment within the datum (matches `keys[subIndex]`). */
+  readonly key: K;
+  /** Numeric value of this segment. */
+  readonly value: number;
+  /** Cumulative offset — where this segment starts (0 for the first key). */
+  readonly base: number;
+  /** `base + value` — where this segment ends. */
+  readonly top: number;
+  /** Index of this segment within its datum (0-based, same order as `keys`). */
+  readonly subIndex: number;
+  /** Index of the source datum in the input array. */
+  readonly datumIndex: number;
+}
+
+export type StackOffset = "zero" | "expand" | "silhouette" | "wiggle";
+export type StackOrder = "input" | "ascending" | "descending" | "inside-out" | "appearance";
+
+export interface StackOptions<T, K extends string = string> {
+  /**
+   * Extract the numeric value for `key` from `datum`. Default: `datum[key]` —
+   * works when the data is a plain object keyed by string.
+   */
+  value?: (datum: T, key: K, datumIndex: number) => number;
+  /**
+   * Baseline offset:
+   * - `"zero"` (default) — bases at 0 going up.
+   * - `"expand"` — normalize each datum to `[0, 1]` (100% stacked).
+   * - `"silhouette"` — center the stack on 0 (`-rowSum/2 .. +rowSum/2`).
+   * - `"wiggle"` — minimize layer wiggle (Byron–Wattenberg streamgraph).
+   */
+  offset?: StackOffset;
+  /**
+   * Series ordering. Reorders the stack from inner-out:
+   * - `"input"` (default) — preserve `keys` order.
+   * - `"ascending"` — smallest total first.
+   * - `"descending"` — largest total first.
+   * - `"inside-out"` — largest in the middle (good for streamgraphs).
+   * - `"appearance"` — by index of each series' max value.
+   */
+  order?: StackOrder;
+}
+
+function orderKeys<T, K extends string>(
+  data: readonly T[],
+  keys: readonly K[],
+  value: (datum: T, key: K, index: number) => number,
+  order: StackOrder,
+): readonly K[] {
+  if (order === "input") return keys;
+
+  const sums = keys.map((k) => {
+    let s = 0;
+    for (let i = 0; i < data.length; i++) s += value(data[i]!, k, i);
+    return s;
+  });
+
+  if (order === "ascending") {
+    return [...keys].sort((a, b) => sums[keys.indexOf(a)]! - sums[keys.indexOf(b)]!);
+  }
+  if (order === "descending") {
+    return [...keys].sort((a, b) => sums[keys.indexOf(b)]! - sums[keys.indexOf(a)]!);
+  }
+  if (order === "appearance") {
+    const peakIndex = keys.map((k) => {
+      let bestIdx = 0;
+      let bestVal = -Number.POSITIVE_INFINITY;
+      for (let i = 0; i < data.length; i++) {
+        const v = value(data[i]!, k, i);
+        if (v > bestVal) {
+          bestVal = v;
+          bestIdx = i;
+        }
+      }
+      return bestIdx;
+    });
+    return [...keys].sort((a, b) => peakIndex[keys.indexOf(a)]! - peakIndex[keys.indexOf(b)]!);
+  }
+  // inside-out: ascending sums to bottom + top alternately so largest sits in middle
+  if (order === "inside-out") {
+    const indexed = keys.map((k, idx) => ({ k, sum: sums[idx]! }));
+    indexed.sort((a, b) => a.sum - b.sum);
+    const bottom: K[] = [];
+    const top: K[] = [];
+    let bottomSum = 0;
+    let topSum = 0;
+    for (const e of indexed) {
+      if (bottomSum < topSum) {
+        bottom.push(e.k);
+        bottomSum += e.sum;
+      } else {
+        top.unshift(e.k);
+        topSum += e.sum;
+      }
+    }
+    return [...bottom, ...top];
+  }
+  return keys;
+}
+
+/**
+ * Flatten `data` into a list of `StackSegment`s — one per (datum, key) pair —
+ * with cumulative `base` / `top` offsets computed per datum. Supports
+ * `offset` (zero / expand / silhouette / wiggle) and `order` (input /
+ * ascending / descending / inside-out / appearance).
+ *
+ * Output order is `data[0].keys[0], data[0].keys[1], ..., data[1].keys[0],
+ * ...` — convenient for `barMark` / `areaMark`. `subIndex` reflects the
+ * post-`order` stacking position (0 = inner-most).
+ */
+export function stack<T, K extends string = string>(
+  data: readonly T[],
+  keys: readonly K[],
+  options: StackOptions<T, K> = {},
+): StackSegment<T, K>[] {
+  const value =
+    options.value ?? ((datum: T, key: K) => (datum as Record<string, number>)[key] ?? 0);
+  const offset = options.offset ?? "zero";
+  const order = options.order ?? "input";
+  const ordered = orderKeys(data, keys, value, order);
+
+  // Per-datum precomputed values + row totals (needed for expand / silhouette / wiggle).
+  const rows: number[][] = data.map((d, i) => ordered.map((k) => value(d, k, i)));
+  const rowSums = rows.map((row) => row.reduce((s, v) => s + v, 0));
+
+  // Compute per-datum baseline (the value subtracted from `base` for each segment).
+  const baselines: number[] = data.map(() => 0);
+  if (offset === "silhouette") {
+    for (let i = 0; i < data.length; i++) baselines[i] = -rowSums[i]! / 2;
+  } else if (offset === "wiggle") {
+    // Byron–Wattenberg wiggle: y[0] = -∑(n-i) * Δprev_i / 2 / ∑Δprev_*
+    // Iteratively compute baseline that minimizes weighted wiggle.
+    if (data.length > 0) {
+      baselines[0] = 0;
+      for (let i = 1; i < data.length; i++) {
+        let n1 = 0;
+        let n2 = 0;
+        for (let k = 0; k < ordered.length; k++) {
+          const di = rows[i]![k]!;
+          const di1 = rows[i - 1]![k]!;
+          let s = 0;
+          for (let j = 0; j < k; j++) s += rows[i]![j]! - rows[i - 1]![j]!;
+          n1 += (s + (di - di1) / 2) * di;
+          n2 += di;
+        }
+        baselines[i] = baselines[i - 1]! - (n2 === 0 ? 0 : n1 / n2);
+      }
+      // Center the wiggle baseline visually.
+      const minB = Math.min(...baselines);
+      const maxB = Math.max(...baselines.map((b, i) => b + rowSums[i]!));
+      const center = (minB + maxB) / 2;
+      for (let i = 0; i < baselines.length; i++) baselines[i] -= center - (maxB - minB) / 2;
+    }
+  }
+
+  const out: StackSegment<T, K>[] = [];
+  for (let i = 0; i < data.length; i++) {
+    const datum = data[i]!;
+    const sum = rowSums[i]!;
+    const scale = offset === "expand" && sum !== 0 ? 1 / sum : 1;
+    let base = baselines[i]!;
+    for (let j = 0; j < ordered.length; j++) {
+      const key = ordered[j]!;
+      const v = rows[i]![j]! * scale;
+      out.push({
+        datum,
+        key,
+        value: v,
+        base,
+        top: base + v,
+        subIndex: j,
+        datumIndex: i,
+      });
+      base += v;
+    }
+  }
+  return out;
+}

package/src/marks.d.ts

@@ -0,0 +1,273 @@
+import { type Color, type Group, type Layer, type LineCap, type LineJoin, type Vec2 } from "insomni";
+import { type LineCurve } from "./marks/curve.ts";
+import { type StackOffset, type StackOrder, type StackSegment } from "./marks/stack.ts";
+import type { BandScale, ContinuousScale, GroupedBandScale } from "./scales.ts";
+export { cardinalCurve, defineCurve, resamplePoints, type CustomCurve, type LineCurve, type LineCurvePreset, } from "./marks/curve.ts";
+export { stack, type StackOffset, type StackOptions, type StackOrder, type StackSegment, } from "./marks/stack.ts";
+export interface MarkOrigin {
+    x?: number;
+    y?: number;
+}
+export interface MarkBuilder {
+    addTo(layer: Layer, origin?: MarkOrigin): Layer;
+    readonly length: number;
+}
+export type Accessor<T, V> = (datum: T, index: number) => V;
+export type ValueOrAccessor<T, V> = V | Accessor<T, V>;
+declare function resolve<T, V>(value: ValueOrAccessor<T, V>, datum: T, index: number): V;
+export { resolve as resolveValueOrAccessor };
+/**
+ * Discrete marker glyphs for `pointMark`. The first four are filled solids;
+ * the `-open` variants render the same outline with no fill (caller must
+ * supply a stroke). `cross`, `plus`, and `star` are filled glyphs whose
+ * "arm" thickness scales with `radius`.
+ */
+export type PointShapeKind = "circle" | "square" | "triangle" | "diamond" | "circle-open" | "square-open" | "triangle-open" | "diamond-open" | "cross" | "plus" | "star";
+/** Shape ordering used by the default categorical shape scale. */
+export declare const POINT_SHAPE_PALETTE: readonly PointShapeKind[];
+/**
+ * Border treatment applied orthogonally to a point's shape kind.
+ *
+ * - `"solid"` (default): existing behavior — fill + optional solid stroke.
+ * - `"open"`: fill is suppressed; stroke uses `stroke ?? fill` as the color
+ *   (equivalent to the `-open` shape variants, but composable with any kind).
+ * - `"dashed"` / `"dotted"`: fill is kept; the stroke is rendered as a polyline
+ *   ring with a dash pattern. Required because SDF strokes don't support
+ *   per-shape dashes; this routes the border through `tessellatePolyline`.
+ */
+export type PointBorderStyle = "solid" | "dashed" | "dotted" | "open";
+/** Line-stroke dash treatment. Maps to polyline `dashPattern`. */
+export type LineDashStyle = "solid" | "dashed" | "dotted";
+/** Default dash pattern emitted for `"dashed"` border/line styles. */
+export declare const DASHED_PATTERN: readonly number[];
+/** Default dash pattern emitted for `"dotted"` border/line styles. */
+export declare const DOTTED_PATTERN: readonly number[];
+export interface PointMarkOptions<T> {
+    x: Accessor<T, number>;
+    y: Accessor<T, number>;
+    radius?: ValueOrAccessor<T, number>;
+    fill?: ValueOrAccessor<T, Color>;
+    stroke?: ValueOrAccessor<T, Color>;
+    strokeWidth?: ValueOrAccessor<T, number>;
+    shape?: ValueOrAccessor<T, PointShapeKind>;
+    /**
+     * Per-datum border treatment (`"solid"` | `"dashed"` | `"dotted"` | `"open"`).
+     * Composes with any shape kind; e.g. `shape: "circle", borderStyle: "open"`
+     * is equivalent to `shape: "circle-open"`. Dashed/dotted borders bypass the
+     * SDF shader (which has no dash support) and route through a polyline ring.
+     */
+    borderStyle?: ValueOrAccessor<T, PointBorderStyle>;
+    /**
+     * Optional secondary glyph drawn on top of the base shape at the same anchor.
+     * Pass `null` to skip overlay for a specific datum. The overlay's radius is
+     * `radius * overlayScale`; its color falls back to the base stroke (or fill
+     * if no stroke) so badges contrast against the base shape.
+     */
+    overlayGlyph?: ValueOrAccessor<T, PointShapeKind | null>;
+    /** Overlay radius as a fraction of the base radius. Default `0.6`. */
+    overlayScale?: ValueOrAccessor<T, number>;
+    /**
+     * Per-datum GPU emphasis key (P5-T3) applied to every primitive a point emits
+     * (base shape + overlay glyph). Used by boxplot/violin point overlays + mean
+     * markers to tag a whole entity's dots with the entity's key. `undefined` →
+     * untagged (no dim).
+     */
+    emphasisKey?: Accessor<T, number | undefined>;
+    group?: Group;
+}
+/**
+ * Emit a filled polygon plus an optional solid stroke outline.
+ *
+ * v3's `PolygonShape` is fill-only (stroke is a separate polyline ring, not a
+ * field), so this mirrors the rect/ellipse stroked-shape pattern: push a
+ * fill-only polygon when a real fill is present, and push a closed-loop
+ * polyline ring over the same points when a stroke is present. A stroke-only
+ * mark (no fill) emits only the ring — v3 requires `fill`, so `pushPolygon` is
+ * never called without one.
+ */
+export declare function pushFilledPolygon(layer: Layer, points: readonly Vec2[], opts: PolygonOpts & {
+    holes?: readonly (readonly Vec2[])[];
+}): void;
+export interface PolygonOpts {
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    group?: Group;
+    /**
+     * GPU emphasis key (P5-T3) threaded onto the polygon fill AND its stroke-ring
+     * polyline so the whole filled shape dims as one unit. `undefined` → untagged
+     * (no dim). Used by boxplot/violin/ridgeline to tag a logical entity's fill.
+     */
+    emphasisKey?: number;
+}
+/**
+ * Single-point swatch emission for legends and other one-off renders.
+ *
+ * Internal helper exported so the legend renderer can produce a swatch that
+ * matches the on-chart point exactly — same shape, border treatment, and
+ * overlay glyph — without re-implementing the dispatch. Composes the same
+ * primitives that `pointMark` calls per datum.
+ */
+export interface PointSwatchEmitOptions {
+    cx: number;
+    cy: number;
+    radius: number;
+    fill: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    shape?: PointShapeKind;
+    borderStyle?: PointBorderStyle;
+    overlayGlyph?: PointShapeKind | null;
+    overlayScale?: number;
+    group?: Group;
+}
+export declare function emitPointSwatch(layer: Layer, opts: PointSwatchEmitOptions): void;
+export declare function pointMark<T>(data: readonly T[], options: PointMarkOptions<T>): MarkBuilder;
+export interface LineMarkOptions<T> {
+    x: Accessor<T, number>;
+    y: Accessor<T, number>;
+    stroke?: Color;
+    strokeWidth?: number;
+    curve?: LineCurve;
+    /** Resample density for smooth curves (`monotone-x`, `basis`). Default `16`. */
+    curveSamples?: number;
+    cap?: LineCap;
+    join?: LineJoin;
+    dashPattern?: readonly number[];
+    dashOffset?: number;
+    /**
+     * Categorical dash treatment. `"solid"` (default) leaves the stroke as a
+     * continuous line; `"dashed"` and `"dotted"` map to default dash patterns.
+     * `dashPattern` takes precedence when both are supplied.
+     */
+    dashStyle?: LineDashStyle;
+    defined?: Accessor<T, boolean>;
+    /**
+     * GPU emphasis key (P5-T3) applied to every polyline segment of this line.
+     * A whole line/series shares one key so it dims/un-dims together. `undefined`
+     * → untagged (no dim).
+     */
+    emphasisKey?: number;
+    group?: Group;
+}
+export declare function lineMark<T>(data: readonly T[], options: LineMarkOptions<T>): MarkBuilder;
+export interface AreaMarkOptions<T> {
+    x: Accessor<T, number>;
+    y0: Accessor<T, number>;
+    y1: Accessor<T, number>;
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    defined?: Accessor<T, boolean>;
+    group?: Group;
+}
+export declare function areaMark<T>(data: readonly T[], options: AreaMarkOptions<T>): MarkBuilder;
+/**
+ * Bar border treatment — shared between `barMark`, `categoricalBarMark`,
+ * `stackedBarMark`, and `groupedBarMark`. Same routing as point borders:
+ * `"open"` suppresses fill; `"dashed"` / `"dotted"` emit a polyline ring
+ * around the rect because SDF rect strokes have no native dash support.
+ */
+export type BarBorderStyle = "solid" | "dashed" | "dotted" | "open";
+export interface BarMarkOptions<T> {
+    x: Accessor<T, number>;
+    y: Accessor<T, number>;
+    width: ValueOrAccessor<T, number>;
+    height: ValueOrAccessor<T, number>;
+    fill?: ValueOrAccessor<T, Color>;
+    stroke?: ValueOrAccessor<T, Color>;
+    strokeWidth?: ValueOrAccessor<T, number>;
+    cornerRadius?: ValueOrAccessor<T, number>;
+    rotation?: ValueOrAccessor<T, number>;
+    /** Per-datum border treatment. See {@link BarBorderStyle}. */
+    borderStyle?: ValueOrAccessor<T, BarBorderStyle>;
+    group?: Group;
+}
+export declare function barMark<T>(data: readonly T[], options: BarMarkOptions<T>): MarkBuilder;
+export type BarOrientation = "y" | "x";
+export interface CategoricalBarMarkOptions<T, C> {
+    /**
+     * `"y"` (default) → vertical bars, value mapped to height.
+     * `"x"` → horizontal bars, value mapped to width.
+     */
+    orientation?: BarOrientation;
+    category: Accessor<T, C>;
+    value: Accessor<T, number>;
+    /** Band scale resolving categories to one of the layer's axes. */
+    categoryScale: BandScale<C>;
+    /** Continuous scale resolving values to the perpendicular axis. */
+    valueScale: ContinuousScale;
+    /** Baseline value (in domain units). Default `0`. */
+    baseline?: number;
+    fill?: ValueOrAccessor<T, Color>;
+    stroke?: ValueOrAccessor<T, Color>;
+    strokeWidth?: ValueOrAccessor<T, number>;
+    cornerRadius?: ValueOrAccessor<T, number>;
+    /** Per-datum border treatment. See {@link BarBorderStyle}. */
+    borderStyle?: ValueOrAccessor<T, BarBorderStyle>;
+    /** Per-datum GPU emphasis key (P5-T3). `undefined` → untagged (no dim). */
+    emphasisKey?: Accessor<T, number | undefined>;
+    group?: Group;
+}
+export declare function categoricalBarMark<T, C>(data: readonly T[], options: CategoricalBarMarkOptions<T, C>): MarkBuilder;
+export interface StackedBarMarkOptions<T, C, K extends string> {
+    orientation?: BarOrientation;
+    category: Accessor<T, C>;
+    categoryScale: BandScale<C>;
+    valueScale: ContinuousScale;
+    /** Per-segment fill — typically `colorScale(palette, keys)` (a function of `K`). */
+    color: (key: K, segment: StackSegment<T, K>) => Color;
+    offset?: StackOffset;
+    order?: StackOrder;
+    value?: (datum: T, key: K, datumIndex: number) => number;
+    cornerRadius?: number;
+    stroke?: Color;
+    strokeWidth?: number;
+    /** Border treatment shared across every segment. See {@link BarBorderStyle}. */
+    borderStyle?: BarBorderStyle;
+    /** Per-segment GPU emphasis key (P5-T3). `undefined` → untagged (no dim). */
+    emphasisKey?: (key: K, segment: StackSegment<T, K>) => number | undefined;
+    group?: Group;
+}
+export interface StackedMarkBuilder<T, K extends string> extends MarkBuilder {
+    /** Per-(datum, key) layout segments — useful for `valueLabelMark` over totals. */
+    readonly segments: readonly StackSegment<T, K>[];
+}
+export declare function stackedBarMark<T, C, K extends string>(data: readonly T[], keys: readonly K[], options: StackedBarMarkOptions<T, C, K>): StackedMarkBuilder<T, K>;
+export interface GroupedBarMarkOptions<T, C, K extends string> {
+    orientation?: BarOrientation;
+    category: Accessor<T, C>;
+    groupedScale: GroupedBandScale<C, K>;
+    valueScale: ContinuousScale;
+    /** Per-key fill — typically `colorScale(palette, keys)`. */
+    color: (key: K) => Color;
+    /** Per-(datum, key) value resolver. Default `datum[key]`. */
+    value?: (datum: T, key: K, datumIndex: number) => number;
+    /** Domain-space baseline. Default `0`. */
+    baseline?: number;
+    cornerRadius?: number;
+    stroke?: Color;
+    strokeWidth?: number;
+    /** Border treatment shared across every bar in the grouped layout. */
+    borderStyle?: BarBorderStyle;
+    /** Per-(datum, key) GPU emphasis key (P5-T3). `undefined` → untagged. */
+    emphasisKey?: (datum: T, key: K, datumIndex: number) => number | undefined;
+    group?: Group;
+}
+export declare function groupedBarMark<T, C, K extends string>(data: readonly T[], options: GroupedBarMarkOptions<T, C, K>): MarkBuilder;
+export interface StackedAreaMarkOptions<T, K extends string> {
+    /** Continuous x position resolver — already in layer-space pixels. */
+    x: Accessor<T, number>;
+    /** Continuous scale that maps stack base/top values to layer-space pixels. */
+    valueScale: ContinuousScale;
+    /** Per-series fill. */
+    color: (key: K) => Color;
+    offset?: StackOffset;
+    order?: StackOrder;
+    value?: (datum: T, key: K, datumIndex: number) => number;
+    defined?: Accessor<T, boolean>;
+    stroke?: Color;
+    strokeWidth?: number;
+    group?: Group;
+}
+export declare function stackedAreaMark<T, K extends string>(data: readonly T[], keys: readonly K[], options: StackedAreaMarkOptions<T, K>): StackedMarkBuilder<T, K>;