insomni-plot 0.1.0-alpha.0

package/src/axis.d.ts

@@ -0,0 +1,184 @@
+import { type Color, type GlyphAtlas, type Layer } from "insomni";
+import { type AxisScale, type TickFormatter, type TimeIntervalUnit } from "./scales.ts";
+/**
+ * Explicit time interval for axis ticks: render one tick per `step × unit`
+ * regardless of how many fit. `quarter` is sugar for `month, step: 3`. Pairs
+ * with {@link AxisOptions.ticks} on time scales — ignored on numeric / band
+ * scales (those fall back to a default tick count).
+ */
+export interface TickIntervalSpec {
+    interval: TimeIntervalUnit;
+    step?: number;
+}
+/**
+ * Tick generation strategy on continuous scales:
+ * - `number` — target count (current default behavior).
+ * - `"auto"` — derive count from the axis's pixel span (~80px/tick horizontal,
+ *   ~50px/tick vertical). Cheap proxy for "as many ticks as comfortably fit."
+ * - `TickIntervalSpec` — explicit time interval (time scales only).
+ *
+ * `undefined` keeps the previous default of {@link DEFAULT_TICKS}.
+ */
+export type TickSpec = number | "auto" | TickIntervalSpec;
+/**
+ * Loose tick formatter signature consumed by the grammar's `AxisSpec.format`.
+ * The runtime calls it with the active scale's tick value — `number` for
+ * linear/log/sqrt, `Date` for time, `string` for band scales. Typed loose so
+ * consumers can write `(v: number) => ...` or `(v: Date) => ...` directly
+ * without a wrapping cast; narrow inside the function to the type your scale
+ * produces.
+ */
+export type AxisTickFormatter = (value: any) => string;
+export interface AxisOrigin {
+    x?: number;
+    y?: number;
+}
+/**
+ * Configuration for axis tick labels. Currently only carries `maxWidth` —
+ * existing `labelFontSize` / `labelColor` / etc. live as flat keys on
+ * `AxisOptions` for back-compat. New per-label knobs go here.
+ */
+export interface AxisLabelConfig {
+    /**
+     * Maximum width in pixels for any tick label. Labels exceeding this width
+     * are truncated to the longest prefix that fits with a trailing ellipsis
+     * (`…`). Requires `atlas` to measure text. When unset, labels render at
+     * their natural width.
+     */
+    maxWidth?: number;
+}
+/**
+ * Axis title — accepts either a plain string or a config object. The object
+ * form lets callers cap the title's rendered width with an ellipsis.
+ */
+export type AxisTitle = string | {
+    text: string;
+    maxWidth?: number;
+};
+export interface AxisOptions<Value> {
+    ticks?: TickSpec;
+    tickValues?: readonly Value[];
+    /**
+     * Render shorter, unlabeled minor tick marks between the major ticks.
+     * - Number `N`: subdivide each major interval into `N` parts (so `N=2`
+     *   places one minor halfway between every adjacent major pair).
+     * - Array: explicit minor tick values, used as-is.
+     *
+     * Minor ticks never render labels and don't affect axis measurement.
+     */
+    minorTicks?: number | readonly Value[];
+    /** Length of minor tick marks. Default `tickSize / 2`. */
+    minorTickSize?: number;
+    /**
+     * Render a tick label only every `N`th major tick. Default `1` (every
+     * major). Use `2` to label every other tick, etc. The hidden ticks still
+     * draw their tick mark and grid line. The first tick is always labeled.
+     */
+    labelStep?: number;
+    /**
+     * Automatic label collision avoidance. `"auto"` measures the
+     * formatted tick labels and inflates `labelStep` until no two visible
+     * labels overlap (with a small padding). Off by default — opt in when
+     * the axis density is data-driven (dense band axes, time axes whose
+     * domain rescales on zoom). Falls back to `labelStep` when no atlas
+     * is available.
+     */
+    labelCollision?: "auto";
+    format?: TickFormatter<Value>;
+    atlas?: GlyphAtlas;
+    labels?: boolean;
+    tickSize?: number;
+    tickWidth?: number;
+    tickColor?: Color;
+    axisLine?: boolean;
+    axisLineWidth?: number;
+    axisLineColor?: Color;
+    /**
+     * Override the axis-line extent in pixels along the axis direction. Defaults
+     * to the scale's range. Pass `[0, plotFrame.width]` (or `.height`) to draw
+     * the spine across the full plot frame even when the data range is inset
+     * (framePadding / `prepareRange` reservations).
+     */
+    axisLineExtent?: readonly [number, number];
+    labelPadding?: number;
+    labelColor?: Color;
+    labelFontSize?: number;
+    labelFontFamily?: string;
+    labelFontWeight?: string;
+    labelFontStyle?: string;
+    /** Per-label configuration (currently `maxWidth` for ellipsis truncation). */
+    label?: AxisLabelConfig;
+    gridLines?: boolean;
+    gridLength?: number;
+    gridWidth?: number;
+    gridColor?: Color;
+    /**
+     * Axis title. Rendered upright alongside the axis — outside the tick
+     * labels for horizontal axes, above the axis line for vertical axes.
+     * Requires `atlas`. Skipped when undefined / empty. Pass an object form
+     * `{ text, maxWidth }` to cap the title width with ellipsis.
+     */
+    title?: AxisTitle;
+    titlePadding?: number;
+    titleFontSize?: number;
+    titleFontFamily?: string;
+    titleFontWeight?: string;
+    titleFontStyle?: string;
+    titleColor?: Color;
+}
+export interface TruncateFontOptions {
+    fontSize: number;
+    fontFamily?: string;
+    fontWeight?: string;
+    fontStyle?: string;
+}
+/**
+ * Truncate `text` so its rendered width fits within `maxWidth`, appending an
+ * ellipsis when the original text is too wide. Returns the original text if
+ * it already fits or if measurement is impossible. Uses binary search over
+ * prefix lengths for O(log n) `measureText` calls.
+ */
+export declare function truncateToWidth(atlas: GlyphAtlas | undefined, text: string, maxWidth: number | undefined, font: TruncateFontOptions): string;
+export interface AxisMeasurement {
+    /**
+     * Total perpendicular space the axis needs. For horizontal axes this is
+     * tick size + label height + (title padding + title height when present),
+     * since the title sits below/above the labels. For vertical axes this is
+     * tick size + label width only — the title for vertical axes is rendered
+     * above the axis (parallel to the value range) and reported separately
+     * via `axialTitleOverhead` so callers can reserve vertical space for it.
+     */
+    readonly thickness: number;
+    /** Maximum measured width across all formatted tick labels. */
+    readonly maxLabelWidth: number;
+    /** Tick label height (font size). */
+    readonly labelHeight: number;
+    /** Whether a title is present and was measured. */
+    readonly hasTitle: boolean;
+    /** Measured title font size (0 if no title). */
+    readonly titleHeight: number;
+    /**
+     * Pixels the axis title needs *along* the value-range axis, on top of the
+     * axis itself. Non-zero only for vertical axes with a title (which is
+     * rendered above the axis line). Horizontal axes return 0 — their title's
+     * footprint is already included in `thickness`.
+     */
+    readonly axialTitleOverhead: number;
+}
+export interface AxisBuilder<Value> {
+    addTo(layer: Layer, origin?: AxisOrigin): Layer;
+    /**
+     * Measure how much room the axis will occupy on its perpendicular axis.
+     * Use the result as `AXIS_MARGIN.bottom/left/...` so callers don't have to
+     * hand-tune padding for long tick labels or axis titles.
+     *
+     * Requires an atlas — pass either `options.atlas` at construction or one
+     * via the `atlas` argument here.
+     */
+    measure(atlas?: GlyphAtlas): AxisMeasurement;
+    readonly tickValues: readonly Value[];
+}
+export declare function bottomAxis<Value>(scale: AxisScale<Value>, options?: AxisOptions<Value>): AxisBuilder<Value>;
+export declare function leftAxis<Value>(scale: AxisScale<Value>, options?: AxisOptions<Value>): AxisBuilder<Value>;
+export declare function topAxis<Value>(scale: AxisScale<Value>, options?: AxisOptions<Value>): AxisBuilder<Value>;
+export declare function rightAxis<Value>(scale: AxisScale<Value>, options?: AxisOptions<Value>): AxisBuilder<Value>;

package/src/axis.test.ts

@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+import { describe, expect, test } from "vite-plus/test";
+
+import { bottomAxis, leftAxis } from "./axis.ts";
+import { bandScale, linearScale, timeScale } from "./scales.ts";
+import { createLayer } from "insomni";
+import { INSTANCE_BYTES } from "insomni/advanced";
+
+interface RecordedText {
+  text: string;
+  x: number;
+  y: number;
+  align?: "left" | "center" | "right";
+}
+
+function makeFakeTextAtlas(): any {
+  return {
+    measureText(text: string, opts: { fontSize: number }) {
+      return { width: text.length * (opts.fontSize ?? 12) * 0.6, height: opts.fontSize ?? 12 };
+    },
+  };
+}
+
+function makeRecordingLayer(): { layer: ReturnType<typeof createLayer>; texts: RecordedText[] } {
+  const texts: RecordedText[] = [];
+  // v3 has no `textPack` layer option — text shapes route through the layer's
+  // `pushText`, which requires an atlas. We mint a layer with a stub atlas and
+  // override `pushText` to record the call (and skip the real glyph shaping).
+  const layer = createLayer({ space: "ui", atlas: makeFakeTextAtlas() });
+  layer.pushText = ((shape: RecordedText) => {
+    texts.push({ text: shape.text, x: shape.x, y: shape.y, align: shape.align });
+    const bbox = { minX: shape.x, minY: shape.y, maxX: shape.x + 1, maxY: shape.y + 1 };
+    return { width: 0, height: 0, layoutHeight: 0, lineCount: 1, bbox, count: 1 };
+  }) as unknown as typeof layer.pushText;
+  return { layer, texts };
+}
+
+describe("axis helpers", () => {
+  test("emit axis, tick, and grid line shapes directly into a layer", () => {
+    const layer = createLayer({ space: "ui" });
+    bottomAxis(linearScale([0, 100], [0, 200]), {
+      ticks: 2,
+      labels: false,
+      gridLines: true,
+      gridLength: 50,
+    }).addTo(layer, { x: 10, y: 80 });
+
+    // 1 axis line + 2 ticks + (axis baseline grid?) → 7 stroked segments.
+    // v3's `Layer.shapeCount` only counts SDF closed shapes (rect/circle/
+    // ellipse); axis lines are segments, so count packed instances directly.
+    const instanceCount = layer.pack.byteLength / INSTANCE_BYTES;
+    expect(instanceCount).toBe(7);
+  });
+
+  test("draws axis geometry without an atlas (labels skipped, no throw)", () => {
+    const layer = createLayer({ space: "ui" });
+
+    // Without an atlas, labels are skipped but geometry (axis line + ticks +
+    // grid lines) still emits — no throw.
+    expect(() =>
+      bottomAxis(linearScale([0, 1], [0, 10]), {
+        ticks: 2,
+        gridLines: true,
+        gridLength: 50,
+      }).addTo(layer, { x: 0, y: 10 }),
+    ).not.toThrow();
+    expect(layer.pack.byteLength / INSTANCE_BYTES).toBeGreaterThan(0);
+  });
+
+  test("center categorical labels within each band", () => {
+    const { layer, texts } = makeRecordingLayer();
+    const atlas = makeFakeTextAtlas();
+    bottomAxis(bandScale(["A", "B"], [0, 100]), {
+      atlas,
+      ticks: 2,
+    }).addTo(layer, { x: 20, y: 50 });
+
+    expect(texts).toHaveLength(2);
+    expect(texts[0]?.text).toBe("A");
+    expect(texts[0]?.x).toBe(45);
+    expect(texts[0]?.align).toBe("center");
+    expect(texts[1]?.text).toBe("B");
+    expect(texts[1]?.x).toBe(95);
+  });
+
+  test("ticks: 'auto' picks count from the axis pixel span", () => {
+    const wide = bottomAxis(linearScale([0, 100], [0, 800]), { ticks: "auto" });
+    // 800px / 80px-per-tick ≈ 10 → ~10 ticks across the domain (snapped to nice steps).
+    expect(wide.tickValues.length).toBeGreaterThanOrEqual(8);
+
+    const narrow = bottomAxis(linearScale([0, 100], [0, 160]), { ticks: "auto" });
+    // 160px / 80px-per-tick ≈ 2 → handful of ticks (nice-snapped).
+    expect(narrow.tickValues.length).toBeLessThanOrEqual(wide.tickValues.length);
+
+    const tall = leftAxis(linearScale([0, 100], [400, 0]), { ticks: "auto" });
+    // Vertical orientation uses tighter spacing (~50px/tick).
+    expect(tall.tickValues.length).toBeGreaterThanOrEqual(5);
+  });
+
+  test("ticks: { interval } emits explicit time ticks on time scales", () => {
+    const scale = timeScale(
+      [new Date("2026-01-01T00:00:00Z"), new Date("2026-12-31T00:00:00Z")],
+      [0, 600],
+    );
+    const monthly = bottomAxis(scale, { ticks: { interval: "month" } });
+    expect(monthly.tickValues).toHaveLength(12);
+
+    const quarterly = bottomAxis(scale, { ticks: { interval: "quarter" } });
+    expect(quarterly.tickValues).toHaveLength(4);
+  });
+
+  test("ticks: { interval } falls back to default count on non-time scales", () => {
+    const numeric = bottomAxis(linearScale([0, 100], [0, 200]), {
+      ticks: { interval: "month" },
+    });
+    // Falls back to DEFAULT_TICKS (5) — numeric `[0, 100]` with step 20.
+    expect(numeric.tickValues).toEqual([0, 20, 40, 60, 80, 100]);
+  });
+
+  test("use end-aligned labels for left axes", () => {
+    const { layer, texts } = makeRecordingLayer();
+    const atlas = makeFakeTextAtlas();
+    leftAxis(linearScale([0, 100], [100, 0]), {
+      ticks: 2,
+      atlas,
+    }).addTo(layer, { x: 40, y: 10 });
+
+    expect(texts.length).toBeGreaterThan(0);
+    expect(texts[0]?.align).toBe("right");
+  });
+});