insomni-plot 0.1.0-alpha.0

package/src/scales.d.ts

@@ -0,0 +1,98 @@
+export type NumericRange = readonly [number, number];
+export type NumericDomain = readonly [number, number];
+export type DateDomain = readonly [Date, Date];
+export type TickFormatter<T> = (value: T) => string;
+export interface ContinuousScale {
+    (value: number): number;
+    readonly domain: NumericDomain;
+    readonly range: NumericRange;
+    invert(value: number): number;
+    ticks(count?: number): readonly number[];
+    tickFormat(count?: number): TickFormatter<number>;
+}
+export interface TimeScale {
+    (value: Date): number;
+    readonly domain: DateDomain;
+    readonly range: NumericRange;
+    invert(value: number): Date;
+    ticks(count?: number): readonly Date[];
+    tickFormat(count?: number): TickFormatter<Date>;
+}
+export interface BandScale<Domain> {
+    (value: Domain): number;
+    readonly domain: readonly Domain[];
+    readonly range: NumericRange;
+    bandwidth(): number;
+    step(): number;
+    ticks(): readonly Domain[];
+    tickFormat(): TickFormatter<Domain>;
+}
+export type AxisScale<Value> = ContinuousScale | TimeScale | BandScale<Value>;
+export interface BandScaleOptions {
+    padding?: number;
+    paddingInner?: number;
+    paddingOuter?: number;
+    align?: number;
+}
+/**
+ * Time interval units accepted by {@link timeTicks} / {@link timeTickFormat}
+ * and by axis `ticks: { interval, step }` specs. `quarter` is sugar for
+ * `month` with step `3 × step`.
+ */
+export type TimeIntervalUnit = "millisecond" | "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function numericTicks(start: number, stop: number, count?: number): readonly number[];
+/** Sign-preserving sqrt: f(-x) = -sqrt(x). Used by `sqrtScale` and viewport. */
+export declare function signedSqrt(value: number): number;
+/** Inverse of `signedSqrt`. */
+export declare function signedSquare(value: number): number;
+export declare function linearScale(domain: NumericDomain, range: NumericRange): ContinuousScale;
+export declare function sqrtScale(domain: NumericDomain, range: NumericRange): ContinuousScale;
+/** Sign-preserving log. Used by `logScale` and viewport transforms. */
+export declare function logTransform(value: number): number;
+/** Inverse of `logTransform`. */
+export declare function logUntransform(value: number): number;
+export declare function logScale(domain: NumericDomain, range: NumericRange): ContinuousScale;
+export declare function timeScale(domain: DateDomain, range: NumericRange): TimeScale;
+/**
+ * Generate UTC tick dates at an explicit interval (e.g. every month, every
+ * 3 weeks, every quarter). Use this when the default `timeScale.ticks(count)`
+ * heuristic picks the wrong granularity for a known cadence. `step` defaults
+ * to `1`. `quarter` is sugar for `month, step: 3`.
+ */
+export declare function timeTicks(domain: DateDomain, unit: TimeIntervalUnit, step?: number): readonly Date[];
+/**
+ * Tick formatter paired with {@link timeTicks}. The label shape is picked
+ * from the unit: years render `"2026"`, months `"Mar 2026"`, days `"Mar 14"`,
+ * etc. — matching the formatter used by {@link timeScale}.
+ */
+export declare function timeTickFormat(unit: TimeIntervalUnit, step?: number): TickFormatter<Date>;
+export declare function bandScale<Domain>(domain: readonly Domain[], range: NumericRange, options?: BandScaleOptions): BandScale<Domain>;
+export interface GroupedBandScale<Outer, Inner> {
+    /** Position (start) of the inner band within `outer`. */
+    (outer: Outer, inner: Inner): number;
+    /** Inner bandwidth — the rendered width of one inner bar. */
+    bandwidth(): number;
+    /** Inner step — distance between adjacent inner band starts. */
+    step(): number;
+    /** Outer band scale this is nested inside. */
+    readonly outer: BandScale<Outer>;
+    /** Ordered keys of the inner band scale. */
+    readonly innerKeys: readonly Inner[];
+}
+export interface GroupedBandScaleOptions {
+    padding?: number;
+    paddingInner?: number;
+    paddingOuter?: number;
+    align?: number;
+}
+/**
+ * Build a nested band scale: each band of the `outer` scale is subdivided
+ * into one inner band per key. Returns a function `(outerKey, innerKey) →
+ * position` plus inner `bandwidth()` and `step()`.
+ *
+ * Use this for grouped bars / dot plots where each category has multiple
+ * series side by side. Outer scale handles category placement and
+ * spacing; inner band controls intra-group layout.
+ */
+export declare function groupedBandScale<Outer, Inner>(outer: BandScale<Outer>, innerKeys: readonly Inner[], options?: GroupedBandScaleOptions): GroupedBandScale<Outer, Inner>;

package/src/scales.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "vite-plus/test";
+
+import {
+  bandScale,
+  linearScale,
+  logScale,
+  sqrtScale,
+  timeScale,
+  timeTickFormat,
+  timeTicks,
+} from "./scales.ts";
+
+describe("scales", () => {
+  test("linearScale maps values, inverts, and generates ticks", () => {
+    const scale = linearScale([0, 100], [0, 500]);
+
+    expect(scale(25)).toBe(125);
+    expect(scale.invert(250)).toBe(50);
+    expect(scale.ticks(5)).toEqual([0, 20, 40, 60, 80, 100]);
+    expect(scale.tickFormat(5)(40)).toBe("40");
+  });
+
+  test("sqrtScale uses signed roots so negative domains still work", () => {
+    const scale = sqrtScale([-9, 16], [0, 100]);
+
+    expect(scale(-4)).toBeCloseTo(14.285714, 5);
+    expect(scale.invert(scale(9))).toBeCloseTo(9, 5);
+  });
+
+  test("logScale rejects domains that cross zero", () => {
+    expect(() => logScale([-1, 10], [0, 100])).toThrow(/same sign/u);
+  });
+
+  test("logScale emits decade ticks for wide spans", () => {
+    const scale = logScale([1, 1000], [0, 300]);
+
+    expect(scale(10)).toBeCloseTo(100, 5);
+    expect(scale.invert(200)).toBeCloseTo(100, 5);
+    expect(scale.ticks(2)).toEqual([1, 10, 100, 1000]);
+  });
+
+  test("timeScale maps UTC dates and formats tick labels", () => {
+    const scale = timeScale(
+      [new Date("2026-01-01T00:00:00.000Z"), new Date("2026-01-01T03:00:00.000Z")],
+      [0, 300],
+    );
+
+    expect(scale(new Date("2026-01-01T01:30:00.000Z"))).toBe(150);
+    expect(scale.invert(200).toISOString()).toBe("2026-01-01T02:00:00.000Z");
+    expect(scale.ticks(3).map((value) => value.toISOString())).toEqual([
+      "2026-01-01T00:00:00.000Z",
+      "2026-01-01T01:00:00.000Z",
+      "2026-01-01T02:00:00.000Z",
+      "2026-01-01T03:00:00.000Z",
+    ]);
+    expect(scale.tickFormat(3)(new Date("2026-01-01T02:00:00.000Z"))).toBe("02:00");
+  });
+
+  test("timeTicks emits ticks at an explicit interval", () => {
+    const monthly = timeTicks(
+      [new Date("2026-01-15T00:00:00Z"), new Date("2026-06-10T00:00:00Z")],
+      "month",
+    );
+    expect(monthly.map((d) => d.toISOString())).toEqual([
+      "2026-02-01T00:00:00.000Z",
+      "2026-03-01T00:00:00.000Z",
+      "2026-04-01T00:00:00.000Z",
+      "2026-05-01T00:00:00.000Z",
+      "2026-06-01T00:00:00.000Z",
+    ]);
+  });
+
+  test("timeTicks 'quarter' is sugar for month/step 3", () => {
+    const quarters = timeTicks(
+      [new Date("2026-01-01T00:00:00Z"), new Date("2026-12-31T00:00:00Z")],
+      "quarter",
+    );
+    expect(quarters.map((d) => d.toISOString())).toEqual([
+      "2026-01-01T00:00:00.000Z",
+      "2026-04-01T00:00:00.000Z",
+      "2026-07-01T00:00:00.000Z",
+      "2026-10-01T00:00:00.000Z",
+    ]);
+  });
+
+  test("timeTickFormat picks label shape from the unit", () => {
+    expect(timeTickFormat("year")(new Date("2026-04-01T00:00:00Z"))).toBe("2026");
+    expect(timeTickFormat("month")(new Date("2026-04-01T00:00:00Z"))).toBe("Apr 2026");
+    expect(timeTickFormat("day")(new Date("2026-04-01T00:00:00Z"))).toBe("Apr 1");
+    expect(timeTickFormat("quarter")(new Date("2026-04-01T00:00:00Z"))).toBe("Apr 2026");
+  });
+
+  test("bandScale returns evenly spaced starts and bandwidth", () => {
+    const scale = bandScale(["a", "b", "c"], [0, 120]);
+
+    expect(scale("a")).toBe(0);
+    expect(scale("b")).toBe(40);
+    expect(scale("c")).toBe(80);
+    expect(scale.bandwidth()).toBe(40);
+    expect(scale.step()).toBe(40);
+    expect(scale.tickFormat()("b")).toBe("b");
+  });
+});