insomni-plot 0.1.0-alpha.0

package/src/grammar/index.ts

@@ -0,0 +1,269 @@
+// ---------------------------------------------------------------------------
+// insomni-plot — grammar of graphics
+// ---------------------------------------------------------------------------
+// High-level ggplot2-style API. Built on top of the low-level imperative
+// primitives at "insomni-plot/core" (raw scales, axes, marks, viewport, …).
+
+// Chart builder
+export {
+  plot,
+  type AxesSpec,
+  type AxisSpec,
+  type AxisTickFormatter,
+  type AxisTooltipContentResolver,
+  type AxisTooltipInfo,
+  type AxisTooltipRow,
+  type Chart,
+  type LegendMergeChannel,
+  type LegendSpec,
+  type MountedChart,
+  type MountedPlot,
+  type MountPlotOptions,
+  type PanZoomConfig,
+  type PanZoomAxes,
+  type ChartPanBounds,
+  type ChartPanBoundsOptions,
+  type PlotSpec,
+  type RenderTarget,
+  type Row,
+  type ScaleOptionsByChannel,
+  type TitleSpec,
+} from "./chart.ts";
+
+// Coordinate systems
+export {
+  coordCartesian,
+  coordPolar,
+  coordRadial,
+  type Coord,
+  type CoordAxesArgs,
+  type CoordPanArgs,
+  type CoordZoomArgs,
+  type CoordPolarOptions,
+  type CoordViewportHandle,
+  type Point,
+} from "./coord.ts";
+
+// Range-preset helper (DOM-aware wrapper around createRangePresets)
+export {
+  attachRangePresets,
+  type AttachedRangePresets,
+  type AttachRangePresetsOptions,
+  type AttachRangePresetsPosition,
+  type AttachRangePresetsUi,
+} from "./attach-presets.ts";
+
+// Brush attach helper (mirrors range-presets / series-readout shape)
+export {
+  createAttachedBrush,
+  type AttachBrushOptions,
+  type AttachedBrush,
+  type AttachedBrushInternal,
+} from "./attach-brush.ts";
+
+// Series-readout (dygraph-style pinned legend)
+export {
+  type AttachedSeriesReadout,
+  type AttachSeriesReadoutOptions,
+  type SeriesReadoutFormat,
+  type SeriesReadoutPosition,
+  type SeriesReadoutRow,
+  type SeriesReadoutSnapshot,
+  type SeriesReadoutUi,
+} from "./interactions/series-readout.ts";
+
+// Geoms (factory functions + per-geom option / channel types)
+export {
+  aggregate,
+  area,
+  band,
+  bar,
+  boxplot,
+  connectedScatter,
+  histogram,
+  interval,
+  line,
+  point,
+  ribbon,
+  ridgeline,
+  rug,
+  rule,
+  smooth,
+  statRolling,
+  text,
+  tile,
+  violin,
+  type AggregateBinBy,
+  type AggregateBinSize,
+  type AggregateBinView,
+  type AggregateBundleResult,
+  type AggregateBundleSummary,
+  type AggregateBundleSummaryKind,
+  type AggregateChannels,
+  type AggregateInnerGeom,
+  type AggregateOptions,
+  type AggregateSummary,
+  type AggregateSummaryKind,
+  type AreaChannels,
+  type AreaOptions,
+  type AreaPosition,
+  type AutoBinSizeInfo,
+  type BandChannels,
+  type BandOptions,
+  type BarChannels,
+  type BarOptions,
+  type BarPosition,
+  type BoxplotChannels,
+  type BoxplotOptions,
+  type ChannelSpec,
+  type CompileContext,
+  type CompiledHitTest,
+  type ConnectedScatterChannels,
+  type ConnectedScatterOptions,
+  type Geom,
+  type GeomKind,
+  type HistogramChannels,
+  type HoveredHit,
+  type HistogramMeasure,
+  type HistogramOptions,
+  type HistogramPosition,
+  type IntervalChannels,
+  type IntervalOptions,
+  type LineChannels,
+  type LineOptions,
+  type PointChannels,
+  type PointOptions,
+  type PointsMode,
+  type ResolvedChannelMap,
+  type RibbonChannels,
+  type RibbonOptions,
+  type RidgelineChannels,
+  type RidgelineFillMode,
+  type RidgelineGeom,
+  type RidgelineInner,
+  type RidgelineOptions,
+  type RidgelineScale,
+  type RugChannels,
+  type RugOptions,
+  type RugSide,
+  type RuleChannels,
+  type RuleOptions,
+  type ScaleBundle,
+  type SmoothChannels,
+  type SmoothLabelOptions,
+  type SmoothMethod,
+  type SmoothOptions,
+  type StatRollingChannels,
+  type StatRollingOptions,
+  type TextChannels,
+  type TextOptions,
+  type TileChannels,
+  type TileNAOptions,
+  type TileOptions,
+  type ViolinChannels,
+  type ViolinInner,
+  type ViolinOptions,
+  type ViolinScale,
+} from "./geoms/index.ts";
+
+// Aesthetic mapping (user-facing channel typing)
+export type { Accessor, Aes } from "./aes.ts";
+
+// Wide → long reshape helpers
+export {
+  fromMatrix,
+  pivotLonger,
+  type FromMatrixOptions,
+  type PivotLongerOptions,
+} from "./data/pivot.ts";
+
+// Annotations (free-form text/box overlays on the chart)
+export { annotate } from "./annotations.ts";
+export type {
+  AnnotationSpec,
+  AnnotationX,
+  AnnotationY,
+  ArrowAnnotationSpec,
+  CalloutAnnotationSpec,
+  FrameAnchorX,
+  FrameAnchorY,
+  TextAnnotationSpec,
+} from "./annotations.ts";
+
+// Faceting
+export type { FacetScales, FacetSpec, FacetStripStyle } from "./facet.ts";
+
+// Scale option types + channel enum
+export type {
+  AlphaScaleOptions,
+  BorderStyleScaleOptions,
+  Channel,
+  ColorScaleOptions,
+  ColorScaleType,
+  OverlayGlyphScaleOptions,
+  PositionScaleOptions,
+  PositionScaleType,
+  ShapeScaleOptions,
+  SizeScaleOptions,
+} from "./scales.ts";
+export { DEFAULT_BORDER_STYLE_PALETTE, DEFAULT_OVERLAY_GLYPH_PALETTE } from "./scales.ts";
+
+// Categorical-encoding combinators (`palettes.distinguishable`, …)
+export {
+  distinguishable,
+  palettes,
+  type DistinguishableOptions,
+  type DistinguishablePalettes,
+  type DistinguishableScheme,
+} from "./palettes.ts";
+
+// Theme
+export {
+  theme,
+  themeDefault,
+  themeMinimalGrid,
+  type Theme,
+  type ThemeAccentKey,
+  type ThemeAccents,
+  type ThemeAxis,
+  type ThemeInteractions,
+  type ThemeLegend,
+  type ThemeMarks,
+  type ThemePalettes,
+  type ThemeSubtitle,
+  type ThemeText,
+  type ThemeTitle,
+  type ThemeTooltipAccents,
+  type Accessibility,
+  type AccessibilityMode,
+  type TextEffects,
+} from "./theme.ts";
+
+export {
+  resolveTextColor,
+  DEFAULT_ACCESSIBILITY,
+  type ContrastMetric,
+  type ResolveTextColorOptions,
+} from "./accessibility.ts";
+
+export type { BlendSpace } from "insomni";
+
+// Axis tick spec — accepted on `AxisSpec.ticks`.
+export type { TickIntervalSpec, TickSpec } from "../axis.ts";
+export type { TimeIntervalUnit } from "../scales.ts";
+
+// Color-utility shorthand for chart-level mark options.
+export type { ColorOrAccent } from "./color-utils.ts";
+
+// Profiling recorder hook (injectable; defaults to no-op)
+export { setRecorderHook, type RecorderHook } from "./profiling.ts";
+
+// Bridge to @phylon/renderer — tip-aligned scales for tree-anchored panels.
+export {
+  cladeStripsToAnnotations,
+  tipScale,
+  type CladeStripAnnotationOptions,
+  type CladeStripLike,
+  type TipAxisLike,
+  type TipScaleOptions,
+} from "./phylo.ts";

package/src/grammar/interactions/_disposable.d.ts

@@ -0,0 +1,5 @@
+export interface Disposable {
+    readonly isDisposed: boolean;
+    dispose(): void;
+}
+export declare function createDisposable(cleanup: () => void): Disposable;

package/src/grammar/interactions/_disposable.ts

@@ -0,0 +1,23 @@
+// Shared disposable guard. Interaction handles all follow the same pattern:
+// methods early-return after disposal, and `dispose()` must be idempotent.
+// Centralizing the flag here removes the per-module `let disposed = false`
+// boilerplate while leaving each module's actual teardown work in place.
+
+export interface Disposable {
+  readonly isDisposed: boolean;
+  dispose(): void;
+}
+
+export function createDisposable(cleanup: () => void): Disposable {
+  let disposed = false;
+  return {
+    get isDisposed() {
+      return disposed;
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      cleanup();
+    },
+  };
+}

package/src/grammar/interactions/_z.d.ts

@@ -0,0 +1,4 @@
+export declare const Z_BRUSH_DRAG = 0;
+export declare const Z_BRUSH_HANDLE_EDGE: number;
+export declare const Z_BRUSH_HANDLE_CORNER: number;
+export declare const Z_HIT_CLOUD_BASE = 1000;

package/src/grammar/interactions/_z.ts

@@ -0,0 +1,16 @@
+// Centralized z-index constants for plot interaction layers.
+//
+// Layering rules of thumb:
+//   - Hit-test clouds (point/region) sit highest so they claim hover ahead
+//     of the brush's drag plane and other plain interaction nodes.
+//   - Brush handles sit above the brush drag plane; corners get a tiny
+//     extra bump so they win over overlapping edge zones at small sizes.
+//   - The brush drag plane lives at insomni's USER_DEFAULT_Z so it slots
+//     in between user-installed nodes and engine-internal nodes.
+import { USER_DEFAULT_Z } from "insomni";
+
+export const Z_BRUSH_DRAG = USER_DEFAULT_Z;
+export const Z_BRUSH_HANDLE_EDGE = USER_DEFAULT_Z + 1;
+export const Z_BRUSH_HANDLE_CORNER = USER_DEFAULT_Z + 2;
+
+export const Z_HIT_CLOUD_BASE = 1000;

package/src/grammar/interactions/brush-selection.test.ts

@@ -0,0 +1,262 @@
+// Integration test: brush + click-selection on the same chart.
+// Verifies the two interactions hold independent state — drag gestures populate
+// `brushed`, press events through the hit-layer populate `selected`, and
+// background-tap clears both. Brush consumes drag-only and selection consumes
+// press-only at the manager level (capability filter), so this test only needs
+// to confirm that the grammar wrappers don't leak their state into each other.
+
+import type {
+  DragPointerInfo,
+  InteractionManager,
+  InteractionNode,
+  InteractionNodeSpec,
+  PointerInfo,
+} from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import type { CompiledHitTest, HoveredHit } from "../geoms/types.ts";
+import { themeDefault } from "../theme.ts";
+import { createGrammarBrush } from "./brush.ts";
+import type { GrammarHitLayer, HitEventContext, HitLayerSubscriber } from "./hit-layer.ts";
+import { createGrammarSelection } from "./selection.ts";
+
+interface CapturedNode {
+  spec: InteractionNodeSpec;
+}
+
+function fakeManager(): {
+  manager: InteractionManager;
+  nodes: CapturedNode[];
+  fireBackgroundTap: () => void;
+} {
+  const nodes: CapturedNode[] = [];
+  const bgHandlers = new Set<() => void>();
+  const manager = {
+    add(spec: InteractionNodeSpec): InteractionNode {
+      const captured: CapturedNode = { spec };
+      nodes.push(captured);
+      return {
+        id: Symbol("node"),
+        update(patch) {
+          captured.spec = { ...captured.spec, ...patch };
+        },
+        destroy() {},
+      };
+    },
+    addPointCloud() {
+      throw new Error("not used");
+    },
+    onBackgroundTap(handler: () => void) {
+      bgHandlers.add(handler);
+      return () => bgHandlers.delete(handler);
+    },
+    onChange() {
+      return () => {};
+    },
+    destroy() {},
+  } as unknown as InteractionManager;
+  return {
+    manager,
+    nodes,
+    fireBackgroundTap: () => {
+      for (const h of bgHandlers) h();
+    },
+  };
+}
+
+function fakeHitLayer(): {
+  layer: GrammarHitLayer;
+  firePress: <T>(compiled: CompiledHitTest<T>, hitIndex: number, p: PointerInfo) => void;
+} {
+  const subscribers: HitLayerSubscriber[] = [];
+  const layer: GrammarHitLayer = {
+    sync() {},
+    subscribe(sub) {
+      subscribers.push(sub);
+      return () => {
+        const i = subscribers.indexOf(sub);
+        if (i >= 0) subscribers.splice(i, 1);
+      };
+    },
+    state() {
+      return { active: null };
+    },
+    subscribeState() {
+      return () => {};
+    },
+    pickAt() {
+      return null;
+    },
+    dispose() {
+      subscribers.length = 0;
+    },
+  };
+  return {
+    layer,
+    firePress: (compiled, hitIndex, pointer) => {
+      const px = compiled.positions[hitIndex * 2]!;
+      const py = compiled.positions[hitIndex * 2 + 1]!;
+      const hit: HoveredHit = {
+        geomKind: compiled.geomKind,
+        dataIndex: compiled.dataIndex[hitIndex] ?? hitIndex,
+        seriesKey: compiled.seriesKey?.[hitIndex],
+        data: compiled.data as readonly unknown[],
+        x: px,
+        y: py,
+      };
+      const ctx: HitEventContext = {
+        hit,
+        compiled: compiled as CompiledHitTest<unknown>,
+        hitIndex,
+        pointer,
+      };
+      for (const sub of subscribers) sub.onPress?.(ctx);
+    },
+  };
+}
+
+const noMods = { shift: false, ctrl: false, meta: false, alt: false };
+function pointer(x: number, y: number): PointerInfo {
+  return {
+    pointerId: 1,
+    type: "mouse",
+    x,
+    y,
+    localX: x,
+    localY: y,
+    buttons: 1,
+    mods: noMods,
+    stopPropagation: () => {},
+  };
+}
+function dragInfo(x: number, y: number): DragPointerInfo {
+  return { ...pointer(x, y), dx: 0, dy: 0 };
+}
+
+interface Row {
+  x: number;
+  y: number;
+}
+function hitFor(
+  positions: number[],
+  indices: number[],
+  data: readonly Row[],
+): CompiledHitTest<Row> {
+  return {
+    geomKind: "point",
+    positions: Float32Array.from(positions),
+    dataIndex: Int32Array.from(indices),
+    pickRadius: 5,
+    channels: {},
+    data,
+  };
+}
+
+const fullBounds = () => ({ x: 0, y: 0, width: 100, height: 100 });
+
+function setup() {
+  const { manager, nodes, fireBackgroundTap } = fakeManager();
+  const { layer: hitLayer, firePress } = fakeHitLayer();
+  const inv = { invalidate: () => {}, dirty: false } as never;
+  const hud = { pushRect: () => hud };
+
+  const brushed: HoveredHit[][] = [];
+  const selected: HoveredHit[][] = [];
+
+  const brush = createGrammarBrush(
+    {
+      manager,
+      bounds: fullBounds,
+      hudLayer: () => hud as never,
+      theme: () => themeDefault,
+      invalidator: inv,
+    },
+    { onChange: (s) => brushed.push(s) },
+  );
+  const selection = createGrammarSelection(
+    { manager, hitLayer },
+    { onChange: (s) => selected.push(s) },
+  );
+
+  return { brush, selection, nodes, brushed, selected, fireBackgroundTap, firePress };
+}
+
+describe("brush + selection coexistence", () => {
+  test("a drag populates brushed but not selected", () => {
+    const { brush, selection, nodes, brushed, selected } = setup();
+    const data: Row[] = [{ x: 30, y: 40 }];
+    const hit = hitFor([30, 40], [0], data);
+    brush.sync([hit]);
+    selection.sync([hit]);
+
+    // nodes[0] = brush create-drag node.
+    nodes[0]!.spec.onDragStart!(pointer(10, 20));
+    nodes[0]!.spec.onDragMove!(dragInfo(60, 70));
+    nodes[0]!.spec.onDragEnd!(pointer(60, 70));
+
+    expect(brush.current().map((h) => h.dataIndex)).toEqual([0]);
+    expect(brushed.length).toBeGreaterThan(0);
+    expect(selection.current()).toEqual([]);
+    expect(selected.length).toBe(0);
+  });
+
+  test("a press through the hit-layer populates selected but not brushed", () => {
+    const { brush, selection, brushed, selected, firePress } = setup();
+    const data: Row[] = [{ x: 30, y: 40 }];
+    const hit = hitFor([30, 40], [0], data);
+    brush.sync([hit]);
+    selection.sync([hit]);
+
+    firePress(hit, 0, pointer(30, 40));
+
+    expect(selection.current().map((h) => h.dataIndex)).toEqual([0]);
+    expect(selected.length).toBe(1);
+    expect(brush.current()).toEqual([]);
+    expect(brush.rect()).toBeNull();
+    expect(brushed.length).toBe(0);
+  });
+
+  test("brush and selection can hold state simultaneously without interfering", () => {
+    const { brush, selection, nodes, firePress } = setup();
+    const data: Row[] = [
+      { x: 20, y: 30 },
+      { x: 60, y: 70 },
+    ];
+    const hit = hitFor([20, 30, 60, 70], [0, 1], data);
+    brush.sync([hit]);
+    selection.sync([hit]);
+
+    // Brush drag covering only row 0.
+    nodes[0]!.spec.onDragStart!(pointer(0, 0));
+    nodes[0]!.spec.onDragMove!(dragInfo(40, 40));
+    nodes[0]!.spec.onDragEnd!(pointer(40, 40));
+    expect(brush.current().map((h) => h.dataIndex)).toEqual([0]);
+
+    // Press selecting row 1 — brush state must stay put.
+    firePress(hit, 1, pointer(60, 70));
+    expect(selection.current().map((h) => h.dataIndex)).toEqual([1]);
+    expect(brush.current().map((h) => h.dataIndex)).toEqual([0]);
+    expect(brush.rect()).not.toBeNull();
+  });
+
+  test("background tap clears both brush and selection", () => {
+    const { brush, selection, nodes, fireBackgroundTap, firePress } = setup();
+    const data: Row[] = [{ x: 30, y: 40 }];
+    const hit = hitFor([30, 40], [0], data);
+    brush.sync([hit]);
+    selection.sync([hit]);
+
+    nodes[0]!.spec.onDragStart!(pointer(10, 20));
+    nodes[0]!.spec.onDragMove!(dragInfo(60, 70));
+    nodes[0]!.spec.onDragEnd!(pointer(60, 70));
+    firePress(hit, 0, pointer(30, 40));
+    expect(brush.current()).toHaveLength(1);
+    expect(selection.current()).toHaveLength(1);
+
+    fireBackgroundTap();
+
+    expect(brush.current()).toEqual([]);
+    expect(brush.rect()).toBeNull();
+    expect(selection.current()).toEqual([]);
+  });
+});

package/src/grammar/interactions/brush.d.ts

@@ -0,0 +1,63 @@
+import { type BrushAxis, type BrushRect, type Color, type CrosshairBounds, type InteractionManager, type Invalidator, type Layer } from "insomni";
+import type { CompiledHitTest, HoveredHit } from "../geoms/types.ts";
+import type { Theme } from "../theme.ts";
+export interface GrammarBrushConfig {
+    /** Which axes the brush spans. Default `"xy"`. */
+    axis?: BrushAxis;
+    /** Translucent fill color. Default theme.axis.color × 0.12 alpha. */
+    fillColor?: Color;
+    /** Outline color. Default theme.axis.color × 0.6 alpha. */
+    strokeColor?: Color;
+    /** Outline width in CSS px. Default 1. */
+    strokeWidth?: number;
+    /**
+     * Enable edge/corner resize handles on the committed rect. Default `true`.
+     * Disable to lock a brush rect to its initial drag.
+     */
+    handles?: boolean;
+    /** Hit-test extent of each handle in CSS px. Default 8. */
+    handleSize?: number;
+    /**
+     * Enable drag-to-move on the committed rect interior. Default `true`. The
+     * rect's size is held constant during the move; off-axis movement is locked
+     * for `axis: "x"` / `"y"` brushes. Disable to lock a brush rect in place.
+     */
+    translate?: boolean;
+    /**
+     * Snap brush rect edges to the nearest hit-test position along the chosen
+     * axis. `true` snaps on the brush's active `axis`; pass `"x"` / `"y"` /
+     * `"xy"` to override. Default `false`. Useful for axis-locked range brushes
+     * over discrete x-ticks. The snap is computed against the live hit-test
+     * positions (refreshed on every `sync()`), so it follows the data.
+     */
+    snap?: boolean | BrushAxis;
+}
+export interface GrammarBrushOptions extends GrammarBrushConfig {
+    /**
+     * Fired when the brushed set changes. Receives one `HoveredHit` per data
+     * row whose hit-test position falls within the brush rect.
+     */
+    onChange?(hits: HoveredHit[]): void;
+}
+export interface GrammarBrushDeps {
+    manager: InteractionManager;
+    /** Plot-frame bounds in element-local CSS px. The brush only fires inside this rect. */
+    bounds: () => CrosshairBounds;
+    hudLayer: () => Layer;
+    theme: () => Theme;
+    invalidator: Invalidator;
+}
+export interface GrammarBrush {
+    /** Replace the active hit-test set after each pipeline run. */
+    sync<T>(hits: readonly CompiledHitTest<T>[]): void;
+    /** Read-only snapshot of the current brushed hits. */
+    current(): HoveredHit[];
+    /** Current brush rect, or null when idle. */
+    rect(): BrushRect | null;
+    /** Imperatively clear the brush. */
+    clear(): void;
+    /** Draw the brush overlay into the hud layer. */
+    draw(): void;
+    dispose(): void;
+}
+export declare function createGrammarBrush(deps: GrammarBrushDeps, opts?: GrammarBrushOptions): GrammarBrush;