insomni-plot 0.1.0-alpha.0

package/src/layout/box.test.ts

@@ -0,0 +1,107 @@
+// @vitest-environment jsdom
+import { describe, expect, test } from "vite-plus/test";
+import { createLayer, type Layer } from "insomni";
+
+import { pad, placeable, spacer, stack } from "./box.ts";
+
+function box(
+  width: number,
+  height: number,
+): { item: ReturnType<typeof placeable>; calls: { x: number; y: number }[] } {
+  const calls: { x: number; y: number }[] = [];
+  const item = placeable({ width, height }, (_layer: Layer, origin) => {
+    calls.push({ x: origin.x, y: origin.y });
+  });
+  return { item, calls };
+}
+
+describe("layout/box", () => {
+  test("stack horizontal sums widths and uses max height", () => {
+    const a = box(10, 20);
+    const b = box(30, 5);
+    const s = stack([a.item, b.item], { direction: "horizontal", gap: 4 });
+    expect(s.measure()).toEqual({ width: 10 + 4 + 30, height: 20 });
+  });
+
+  test("stack vertical sums heights and uses max width", () => {
+    const a = box(10, 20);
+    const b = box(30, 5);
+    const s = stack([a.item, b.item], { direction: "vertical", gap: 4 });
+    expect(s.measure()).toEqual({ width: 30, height: 20 + 4 + 5 });
+  });
+
+  test("stack vertical with align=start places items flush left", () => {
+    const a = box(10, 20);
+    const b = box(30, 5);
+    const layer = createLayer({ space: "ui" });
+    const s = stack([a.item, b.item], { direction: "vertical", align: "start" });
+    s.addTo(layer, { x: 100, y: 200 });
+    expect(a.calls[0]).toEqual({ x: 100, y: 200 });
+    expect(b.calls[0]).toEqual({ x: 100, y: 220 });
+  });
+
+  test("stack vertical with align=center centers narrower items", () => {
+    const a = box(10, 20);
+    const b = box(30, 5);
+    const layer = createLayer({ space: "ui" });
+    const s = stack([a.item, b.item], { direction: "vertical", align: "center" });
+    s.addTo(layer, { x: 0, y: 0 });
+    // a (width 10) centered in 30 → x=10
+    expect(a.calls[0]).toEqual({ x: 10, y: 0 });
+    expect(b.calls[0]).toEqual({ x: 0, y: 20 });
+  });
+
+  test("stack vertical with align=end right-aligns narrower items", () => {
+    const a = box(10, 20);
+    const b = box(30, 5);
+    const layer = createLayer({ space: "ui" });
+    const s = stack([a.item, b.item], { direction: "vertical", align: "end" });
+    s.addTo(layer, { x: 0, y: 0 });
+    expect(a.calls[0]).toEqual({ x: 20, y: 0 });
+    expect(b.calls[0]).toEqual({ x: 0, y: 20 });
+  });
+
+  test("stack honors gap when placing", () => {
+    const a = box(10, 10);
+    const b = box(10, 10);
+    const layer = createLayer({ space: "ui" });
+    const s = stack([a.item, b.item], { direction: "vertical", gap: 7 });
+    s.addTo(layer, { x: 0, y: 0 });
+    expect(b.calls[0]).toEqual({ x: 0, y: 17 });
+  });
+
+  test("pad expands bbox and offsets child", () => {
+    const a = box(10, 10);
+    const p = pad(a.item, { top: 2, left: 3, right: 4, bottom: 5 });
+    expect(p.measure()).toEqual({ width: 17, height: 17 });
+    const layer = createLayer({ space: "ui" });
+    p.addTo(layer, { x: 100, y: 100 });
+    expect(a.calls[0]).toEqual({ x: 103, y: 102 });
+  });
+
+  test("spacer occupies space but draws nothing", () => {
+    const sp = spacer(20, 10);
+    expect(sp.measure()).toEqual({ width: 20, height: 10 });
+    const layer = createLayer({ space: "ui" });
+    sp.addTo(layer, { x: 0, y: 0 });
+    // no throw, no calls
+  });
+
+  test("nested stack composes correctly", () => {
+    // [title (40w 10h)]
+    // [bar  (12w 80h)]  ← stacked vertical, align=start
+    // overall bbox: 40 wide, 92 tall (gap=2)
+    const title = box(40, 10);
+    const bar = box(12, 80);
+    const s = stack([title.item, bar.item], {
+      direction: "vertical",
+      align: "start",
+      gap: 2,
+    });
+    expect(s.measure()).toEqual({ width: 40, height: 92 });
+    const layer = createLayer({ space: "ui" });
+    s.addTo(layer, { x: 0, y: 0 });
+    expect(title.calls[0]).toEqual({ x: 0, y: 0 });
+    expect(bar.calls[0]).toEqual({ x: 0, y: 12 });
+  });
+});

package/src/layout/box.ts

@@ -0,0 +1,143 @@
+// ---------------------------------------------------------------------------
+// Box layout primitive — Placeable + stack/pad/spacer
+// ---------------------------------------------------------------------------
+// Small, generic abstraction shared by guides (legend, colorBar), the chart
+// title block, and any future overlay that needs "measured boxes arranged
+// without overlap". Inspired by ggplot2's guide layout (legend.box,
+// legend.box.just, legend.spacing) but kept deliberately minimal — we don't
+// have a use case for a constraint solver, only for stacking measured items.
+//
+// Two operations cover every recurring shape in the codebase:
+//   stack(items, { direction, align, gap })  — flow children along an axis
+//   pad(item, { top, right, bottom, left })  — wrap with margin
+//
+// Plus two adapters: `placeable(measure, draw)` to lift any measure/draw pair
+// into a Placeable, and `spacer(w, h)` for empty space.
+
+import type { Layer } from "insomni";
+
+export interface MeasuredBox {
+  width: number;
+  height: number;
+}
+
+export interface BoxOrigin {
+  x: number;
+  y: number;
+}
+
+/**
+ * A measure-then-place rectangle. Implementations must return a stable
+ * `measure()` (called by parents to size themselves) and an `addTo` that
+ * draws into a layer at the given top-left.
+ */
+export interface Placeable {
+  measure(): MeasuredBox;
+  addTo(layer: Layer, origin: BoxOrigin): void;
+}
+
+export type StackDirection = "horizontal" | "vertical";
+export type StackAlign = "start" | "center" | "end";
+
+export interface StackOptions {
+  direction: StackDirection;
+  /** Cross-axis alignment. Default `"start"`. */
+  align?: StackAlign;
+  /** Pixel gap between items. Default `0`. */
+  gap?: number;
+}
+
+/**
+ * Lay out `items` along one axis. The stack's bbox is the sum of children
+ * along the main axis (plus gaps) and the max along the cross axis.
+ *
+ * Children are measured **once** at construction; `measure()` and `addTo()`
+ * are O(items) thereafter. If you need to refresh measurements, build a new
+ * stack.
+ */
+export function stack(items: readonly Placeable[], opts: StackOptions): Placeable {
+  const direction = opts.direction;
+  const align: StackAlign = opts.align ?? "start";
+  const gap = opts.gap ?? 0;
+
+  const measured = items.map((i) => i.measure());
+  let main = 0;
+  let cross = 0;
+  for (let k = 0; k < measured.length; k++) {
+    const m = measured[k]!;
+    const mainExtent = direction === "horizontal" ? m.width : m.height;
+    const crossExtent = direction === "horizontal" ? m.height : m.width;
+    if (k > 0) main += gap;
+    main += mainExtent;
+    if (crossExtent > cross) cross = crossExtent;
+  }
+
+  const total: MeasuredBox =
+    direction === "horizontal" ? { width: main, height: cross } : { width: cross, height: main };
+
+  return {
+    measure: () => total,
+    addTo(layer, origin) {
+      let off = 0;
+      const crossSize = direction === "horizontal" ? total.height : total.width;
+      for (let k = 0; k < items.length; k++) {
+        const m = measured[k]!;
+        const mainExtent = direction === "horizontal" ? m.width : m.height;
+        const crossExtent = direction === "horizontal" ? m.height : m.width;
+        const crossOff =
+          align === "start"
+            ? 0
+            : align === "end"
+              ? crossSize - crossExtent
+              : (crossSize - crossExtent) / 2;
+        const x = origin.x + (direction === "horizontal" ? off : crossOff);
+        const y = origin.y + (direction === "horizontal" ? crossOff : off);
+        items[k]!.addTo(layer, { x, y });
+        off += mainExtent + gap;
+      }
+    },
+  };
+}
+
+export interface Padding {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+
+/** Wrap `item` so its bbox includes uniform or per-side margin. */
+export function pad(item: Placeable, p: Padding): Placeable {
+  const top = p.top ?? 0;
+  const right = p.right ?? 0;
+  const bottom = p.bottom ?? 0;
+  const left = p.left ?? 0;
+  const inner = item.measure();
+  const total: MeasuredBox = {
+    width: inner.width + left + right,
+    height: inner.height + top + bottom,
+  };
+  return {
+    measure: () => total,
+    addTo(layer, origin) {
+      item.addTo(layer, { x: origin.x + left, y: origin.y + top });
+    },
+  };
+}
+
+/** A degenerate Placeable that occupies space but draws nothing. */
+export function spacer(width: number, height: number): Placeable {
+  const m: MeasuredBox = { width, height };
+  return {
+    measure: () => m,
+    addTo: () => {},
+  };
+}
+
+/** Lift a measure + draw pair into a Placeable. */
+export function placeable(
+  measure: MeasuredBox,
+  draw: (layer: Layer, origin: BoxOrigin) => void,
+): Placeable {
+  return { measure: () => measure, addTo: draw };
+}

package/src/legend.d.ts

@@ -0,0 +1,115 @@
+import { type Color, type FrameRect, type GlyphAtlas, type Group } from "insomni";
+import { type Placeable } from "./layout/box.ts";
+import { type PointBorderStyle, type PointShapeKind } from "./marks.ts";
+export interface PointSwatchSpec {
+    kind: "point";
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    shape?: PointShapeKind;
+    /** Default `5`. */
+    radius?: number;
+    /** Per-shape border treatment — matches the mark side. Default `"solid"`. */
+    borderStyle?: PointBorderStyle;
+    /** Optional secondary glyph drawn on the same anchor. `null`/undefined = none. */
+    overlayGlyph?: PointShapeKind | null;
+    /** Overlay radius as a fraction of `radius`. Default `0.6`. */
+    overlayScale?: number;
+}
+export interface LineSwatchSpec {
+    kind: "line";
+    stroke: Color;
+    strokeWidth?: number;
+    dashPattern?: readonly number[];
+    /** Default `18`. */
+    width?: number;
+}
+export interface BarSwatchSpec {
+    kind: "bar";
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    cornerRadius?: number;
+    /** Default `12`. */
+    size?: number;
+}
+export interface AreaSwatchSpec {
+    kind: "area";
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    /** Default `14` (slight rectangle, not a square). */
+    width?: number;
+    /** Default `8`. */
+    height?: number;
+}
+export type SwatchSpec = PointSwatchSpec | LineSwatchSpec | BarSwatchSpec | AreaSwatchSpec;
+export declare function pointSwatch(opts: Omit<PointSwatchSpec, "kind">): PointSwatchSpec;
+export declare function lineSwatch(opts: Omit<LineSwatchSpec, "kind">): LineSwatchSpec;
+export declare function barSwatch(opts: Omit<BarSwatchSpec, "kind">): BarSwatchSpec;
+export declare function areaSwatch(opts: Omit<AreaSwatchSpec, "kind">): AreaSwatchSpec;
+export interface LegendEntry {
+    label: string;
+    swatch: SwatchSpec;
+    /** Optional hint for interactivity layers to render the entry as "off". */
+    hidden?: boolean;
+}
+export type LegendOrientation = "horizontal" | "vertical";
+export type LegendAlign = "start" | "end";
+export interface LegendOptions {
+    atlas: GlyphAtlas;
+    orientation?: LegendOrientation;
+    /** Anchor inside the layout box. Default `"start"` (left/top edge of box). */
+    align?: LegendAlign;
+    fontSize?: number;
+    fontStyle?: string;
+    labelColor?: Color;
+    /** Pixel gap between swatch and label. Default `6`. */
+    swatchGap?: number;
+    /** Pixel gap between entries. Default `14` (horizontal) or `4` (vertical). */
+    entryGap?: number;
+    /** Optional title rendered above the entries (left-aligned, bold). */
+    title?: string;
+    titleFontSize?: number;
+    titleColor?: Color;
+    /** Pixel gap between title and entries. Default `4`. */
+    titleGap?: number;
+    /** Alpha for hidden entries. Default `0.2`. */
+    dimAlpha?: number;
+    group?: Group;
+}
+export interface LegendBuilder extends Placeable {
+    /** Number of entries (or, for color bars, palette samples). */
+    readonly length: number;
+    /** Total laid-out width and height in layer-space pixels. */
+    measure(): {
+        width: number;
+        height: number;
+    };
+    /** Bounding boxes of each entry, relative to the legend's top-left. */
+    getEntryBboxes(): (FrameRect & {
+        label: string;
+    })[];
+}
+/**
+ * `Guide` is the shared shape every legend-like component (categorical
+ * `legend()`, continuous `colorBar()`, future `sizeGuide()` / `shapeGuide()`)
+ * returns. It's a `Placeable` so the chart layout engine can size and place
+ * it generically. Concrete builders may add extra fields (e.g. `length`).
+ */
+export type Guide = Placeable;
+/**
+ * Lay out a row (or column) of swatch + label pairs. Each mark contributes
+ * its own swatch shape via the `*Swatch(...)` helpers, so a dashed line shows
+ * a dashed swatch, a triangle point shows a triangle, etc.
+ *
+ * The legend is positioned by `origin` when added: `origin` is the *top-left*
+ * of the layout box. To right-align, measure first then offset:
+ *
+ * ```ts
+ * const lg = legend(entries, { atlas: a });
+ * const { width } = lg.measure();
+ * lg.addTo(layer, { x: outer.x + outer.width - width, y: outer.y });
+ * ```
+ */
+export declare function legend(entries: readonly LegendEntry[], options: LegendOptions): LegendBuilder;