insomni-plot 0.1.0-alpha.0

package/src/core.ts

@@ -0,0 +1,299 @@
+// ---------------------------------------------------------------------------
+// Scales
+// ---------------------------------------------------------------------------
+
+export {
+  bandScale,
+  groupedBandScale,
+  linearScale,
+  logScale,
+  sqrtScale,
+  timeScale,
+  timeTickFormat,
+  timeTicks,
+  type AxisScale,
+  type BandScale,
+  type BandScaleOptions,
+  type ContinuousScale,
+  type DateDomain,
+  type GroupedBandScale,
+  type GroupedBandScaleOptions,
+  type NumericDomain,
+  type NumericRange,
+  type TickFormatter,
+  type TimeIntervalUnit,
+  type TimeScale,
+} from "./scales.ts";
+
+// ---------------------------------------------------------------------------
+// Axis builders
+// ---------------------------------------------------------------------------
+
+export { bottomAxis, leftAxis, rightAxis, topAxis, truncateToWidth } from "./axis.ts";
+export type {
+  AxisBuilder,
+  AxisLabelConfig,
+  AxisMeasurement,
+  AxisOptions,
+  AxisOrigin,
+  AxisTickFormatter,
+  AxisTitle,
+  TickIntervalSpec,
+  TickSpec,
+} from "./axis.ts";
+
+// ---------------------------------------------------------------------------
+// Marks
+// ---------------------------------------------------------------------------
+
+export {
+  areaMark,
+  barMark,
+  cardinalCurve,
+  categoricalBarMark,
+  DASHED_PATTERN,
+  defineCurve,
+  DOTTED_PATTERN,
+  groupedBarMark,
+  lineMark,
+  pointMark,
+  resamplePoints,
+  stack,
+  stackedAreaMark,
+  stackedBarMark,
+} from "./marks.ts";
+export type {
+  Accessor,
+  AreaMarkOptions,
+  BarBorderStyle,
+  BarMarkOptions,
+  BarOrientation,
+  CategoricalBarMarkOptions,
+  CustomCurve,
+  GroupedBarMarkOptions,
+  LineCurve,
+  LineCurvePreset,
+  LineDashStyle,
+  LineMarkOptions,
+  MarkBuilder,
+  MarkOrigin,
+  PointBorderStyle,
+  PointMarkOptions,
+  PointShapeKind,
+  StackedAreaMarkOptions,
+  StackedBarMarkOptions,
+  StackedMarkBuilder,
+  StackOffset,
+  StackOptions,
+  StackOrder,
+  StackSegment,
+  ValueOrAccessor,
+} from "./marks.ts";
+
+// ---------------------------------------------------------------------------
+// Annotations (rule, band, value labels)
+// ---------------------------------------------------------------------------
+
+export { bandMark, ruleMark, valueLabelMark } from "./annotations.ts";
+export type {
+  BandMarkOptions,
+  HorizontalBandOptions,
+  HorizontalRuleOptions,
+  RuleAnchor,
+  RuleMarkOptions,
+  ValueLabelAlign,
+  ValueLabelMarkOptions,
+  VerticalBandOptions,
+  VerticalRuleOptions,
+} from "./annotations.ts";
+
+// ---------------------------------------------------------------------------
+// Legend
+// ---------------------------------------------------------------------------
+
+export { areaSwatch, barSwatch, legend, lineSwatch, pointSwatch } from "./legend.ts";
+export type {
+  AreaSwatchSpec,
+  BarSwatchSpec,
+  LegendAlign,
+  LegendBuilder,
+  LegendEntry,
+  LegendOptions,
+  LegendOrientation,
+  LineSwatchSpec,
+  PointSwatchSpec,
+  SwatchSpec,
+} from "./legend.ts";
+
+// ---------------------------------------------------------------------------
+// Number / currency / percent formatters
+// ---------------------------------------------------------------------------
+
+export { currency, fixed, percent, siNumber } from "./format.ts";
+export type {
+  CurrencyOptions,
+  FixedNumberOptions,
+  PercentOptions,
+  SiNumberOptions,
+} from "./format.ts";
+
+// ---------------------------------------------------------------------------
+// Heatmap producer
+// ---------------------------------------------------------------------------
+
+export { heatmapLayer } from "./heatmap.ts";
+export type { HeatmapProducer, HeatmapSpec } from "./heatmap.ts";
+
+// ---------------------------------------------------------------------------
+// Color palettes
+// ---------------------------------------------------------------------------
+
+export {
+  accent,
+  blues,
+  brbg,
+  categoricalPalette,
+  category10,
+  cividis,
+  colorScale,
+  continuousPalette,
+  coolwarm,
+  dark2,
+  greens,
+  greys,
+  inferno,
+  magma,
+  oranges,
+  paired,
+  pastel,
+  piyg,
+  plasma,
+  prgn,
+  puor,
+  purples,
+  rdbu,
+  reds,
+  set1,
+  set2,
+  set3,
+  spectral,
+  tableau10,
+  viridis,
+  type CategoricalPalette,
+  type ContinuousPalette,
+} from "./colors.ts";
+
+// ---------------------------------------------------------------------------
+// Data viewport
+// ---------------------------------------------------------------------------
+
+export { createDataViewport, linkViewports } from "./viewport.ts";
+export type {
+  BandAxisConfig,
+  ContinuousAxisConfig,
+  DataPanBoundsOptions,
+  DataViewport,
+  DataViewportOptions,
+  LinkViewportsOptions,
+  TimeAxisConfig,
+  Viewport,
+  ViewportAxisConfig,
+  VisibleDomainInput,
+} from "./viewport.ts";
+
+// ---------------------------------------------------------------------------
+// Data viewport interactions
+// ---------------------------------------------------------------------------
+
+export { bindDataViewport } from "./interactions.ts";
+export type {
+  AxisSelection,
+  BindDataViewportOptions,
+  DataViewportBinding,
+} from "./interactions.ts";
+
+// ---------------------------------------------------------------------------
+// Distribution statistics (box stats, KDE, jitter helpers)
+// ---------------------------------------------------------------------------
+
+export {
+  bin,
+  binBreaks,
+  binBy,
+  binWithBreaks,
+  boxStats,
+  confidenceBand,
+  groupBy,
+  histogramMeasureValue,
+  jitter,
+  kde,
+  linearFit,
+  loessFit,
+  polyFit,
+  quantile,
+  rollingWindow,
+} from "./stats/index.ts";
+export type {
+  BinByOptions,
+  BinByResult,
+  BinClosed,
+  BinOptions,
+  BinResult,
+  BinRule,
+  BoxStats,
+  BoxStatsOptions,
+  ConfidenceBandOptions,
+  ConfidenceBandPoint,
+  HistogramMeasure,
+  KdeBandwidth,
+  KdeKernel,
+  KdeOptions,
+  KdeResult,
+  LoessOptions,
+  QuantileMethod,
+  RegressionFit,
+  RollingAxis,
+  RollingPoint,
+  RollingStatistic,
+  RollingStatisticKind,
+  RollingWindow,
+  RollingWindowOptions,
+  WhiskerRule,
+} from "./stats/index.ts";
+
+// ---------------------------------------------------------------------------
+// Continuous color-bar legend
+// ---------------------------------------------------------------------------
+
+export { colorBar } from "./colorbar.ts";
+export type { ColorBarLabelSide, ColorBarOptions, ColorBarOrientation } from "./colorbar.ts";
+
+// ---------------------------------------------------------------------------
+// Data navigator
+// ---------------------------------------------------------------------------
+
+export { createDataNavigator } from "./navigator.ts";
+export type {
+  DataNavigator,
+  DataNavigatorAxes,
+  DataNavigatorIndicatorOptions,
+  DataNavigatorInteractionOptions,
+  DataNavigatorOptions,
+} from "./navigator.ts";
+
+// ---------------------------------------------------------------------------
+// Axis-range presets
+// ---------------------------------------------------------------------------
+
+export { createRangePresets, linearPreset, logPreset, timePreset } from "./range-presets.ts";
+export type {
+  RangePreset,
+  RangePresetAxis,
+  RangePresetContext,
+  RangePresetDataDomain,
+  RangePresetDomain,
+  RangePresetsController,
+  RangePresetsOptions,
+  RangePresetsSubscriber,
+  TimePresetKey,
+} from "./range-presets.ts";

package/src/format.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Estimated glyph-advance as a fraction of font size, used when a real
+ * `GlyphAtlas.measureText` isn't available yet (first frame before font
+ * load). Sized for proportional sans fonts at typical UI sizes — over-
+ * shoots narrow glyphs and undershoots wide ones, but close enough for
+ * tooltip/menu/annotation box layout fallbacks.
+ */
+export declare const TEXT_WIDTH_FALLBACK_RATIO = 0.55;
+export interface SiNumberOptions {
+    /** Significant fraction digits after auto-scaling. Default `1`. */
+    precision?: number;
+    /** Trim trailing zeros (e.g. `1.0k` → `1k`). Default `true`. */
+    trim?: boolean;
+    /** Optional unit appended after the suffix (`siNumber(1500, { unit: "B" })` → `1.5kB`). */
+    unit?: string;
+}
+/**
+ * Format a number with SI suffix (`k`, `M`, `B`, `T`, `m`, `µ`, `n`).
+ * Negatives keep their sign. NaN → `"NaN"`. ±Infinity → `"∞"` / `"-∞"`.
+ */
+export declare function siNumber(value: number, options?: SiNumberOptions): string;
+export interface CurrencyOptions {
+    /** Currency symbol. Default `"$"`. */
+    symbol?: string;
+    /** Where the symbol goes. Default `"prefix"`. */
+    position?: "prefix" | "suffix";
+    /** Significant fraction digits. Default `1`. */
+    precision?: number;
+    /** Trim trailing zeros. Default `true`. */
+    trim?: boolean;
+}
+/**
+ * Currency-flavoured `siNumber` — `$1.2B`, `$420M`, `$50k`. The symbol can
+ * also go on the right (`1.2B €`) by setting `position: "suffix"`.
+ */
+export declare function currency(value: number, options?: CurrencyOptions): string;
+export interface PercentOptions {
+    /** Fraction digits. Default `0`. */
+    precision?: number;
+    /**
+     * If `true`, the input is a fraction (`0.42` → `"42%"`). If `false`, the
+     * input is already in percent units (`42` → `"42%"`). Default `false`.
+     */
+    fraction?: boolean;
+}
+/** Format `42` (or `0.42` with `fraction: true`) as `"42%"`. */
+export declare function percent(value: number, options?: PercentOptions): string;
+export interface FixedNumberOptions {
+    precision?: number;
+    /** Optional unit suffix (e.g. `" ms"`). */
+    unit?: string;
+}
+/** Plain `value.toFixed(precision)` plus optional unit. Useful for axes. */
+export declare function fixed(value: number, options?: FixedNumberOptions): string;

package/src/format.ts

@@ -0,0 +1,138 @@
+// ---------------------------------------------------------------------------
+// Number / currency / percent formatters
+//
+// Useful as `format` arg to `bottomAxis` / `leftAxis`, and as `text`
+// formatters inside `valueLabelMark`. All return `string`.
+// ---------------------------------------------------------------------------
+
+/**
+ * Estimated glyph-advance as a fraction of font size, used when a real
+ * `GlyphAtlas.measureText` isn't available yet (first frame before font
+ * load). Sized for proportional sans fonts at typical UI sizes — over-
+ * shoots narrow glyphs and undershoots wide ones, but close enough for
+ * tooltip/menu/annotation box layout fallbacks.
+ */
+export const TEXT_WIDTH_FALLBACK_RATIO = 0.55;
+
+export interface SiNumberOptions {
+  /** Significant fraction digits after auto-scaling. Default `1`. */
+  precision?: number;
+  /** Trim trailing zeros (e.g. `1.0k` → `1k`). Default `true`. */
+  trim?: boolean;
+  /** Optional unit appended after the suffix (`siNumber(1500, { unit: "B" })` → `1.5kB`). */
+  unit?: string;
+}
+
+const SI_THRESHOLDS: readonly { v: number; s: string }[] = [
+  { v: 1e12, s: "T" },
+  { v: 1e9, s: "B" },
+  { v: 1e6, s: "M" },
+  { v: 1e3, s: "k" },
+];
+
+const SI_SMALL: readonly { v: number; s: string }[] = [
+  { v: 1e-3, s: "m" },
+  { v: 1e-6, s: "µ" },
+  { v: 1e-9, s: "n" },
+];
+
+function trimTrailing(s: string): string {
+  if (!s.includes(".")) return s;
+  return s.replace(/\.?0+$/u, "");
+}
+
+/**
+ * Format a number with SI suffix (`k`, `M`, `B`, `T`, `m`, `µ`, `n`).
+ * Negatives keep their sign. NaN → `"NaN"`. ±Infinity → `"∞"` / `"-∞"`.
+ */
+export function siNumber(value: number, options: SiNumberOptions = {}): string {
+  const precision = options.precision ?? 1;
+  const trim = options.trim ?? true;
+  const unitSuffix = options.unit ?? "";
+
+  if (Number.isNaN(value)) return "NaN";
+  if (!Number.isFinite(value)) return value > 0 ? "∞" : "-∞";
+  if (value === 0) return `0${unitSuffix}`;
+
+  const sign = value < 0 ? "-" : "";
+  const abs = Math.abs(value);
+
+  for (const { v, s } of SI_THRESHOLDS) {
+    if (abs >= v) {
+      const scaled = abs / v;
+      const text = scaled.toFixed(precision);
+      return `${sign}${trim ? trimTrailing(text) : text}${s}${unitSuffix}`;
+    }
+  }
+  if (abs >= 1) {
+    const text = abs.toFixed(precision);
+    return `${sign}${trim ? trimTrailing(text) : text}${unitSuffix}`;
+  }
+  for (const { v, s } of SI_SMALL) {
+    if (abs >= v) {
+      const scaled = abs / v;
+      const text = scaled.toFixed(precision);
+      return `${sign}${trim ? trimTrailing(text) : text}${s}${unitSuffix}`;
+    }
+  }
+  // Fallback for very small numbers — exponential.
+  return `${sign}${abs.toExponential(precision)}${unitSuffix}`;
+}
+
+export interface CurrencyOptions {
+  /** Currency symbol. Default `"$"`. */
+  symbol?: string;
+  /** Where the symbol goes. Default `"prefix"`. */
+  position?: "prefix" | "suffix";
+  /** Significant fraction digits. Default `1`. */
+  precision?: number;
+  /** Trim trailing zeros. Default `true`. */
+  trim?: boolean;
+}
+
+/**
+ * Currency-flavoured `siNumber` — `$1.2B`, `$420M`, `$50k`. The symbol can
+ * also go on the right (`1.2B €`) by setting `position: "suffix"`.
+ */
+export function currency(value: number, options: CurrencyOptions = {}): string {
+  const symbol = options.symbol ?? "$";
+  const position = options.position ?? "prefix";
+  const formatted = siNumber(value, { precision: options.precision, trim: options.trim });
+
+  if (formatted.startsWith("-")) {
+    const body = formatted.slice(1);
+    return position === "prefix" ? `-${symbol}${body}` : `-${body}${symbol}`;
+  }
+  return position === "prefix" ? `${symbol}${formatted}` : `${formatted}${symbol}`;
+}
+
+export interface PercentOptions {
+  /** Fraction digits. Default `0`. */
+  precision?: number;
+  /**
+   * If `true`, the input is a fraction (`0.42` → `"42%"`). If `false`, the
+   * input is already in percent units (`42` → `"42%"`). Default `false`.
+   */
+  fraction?: boolean;
+}
+
+/** Format `42` (or `0.42` with `fraction: true`) as `"42%"`. */
+export function percent(value: number, options: PercentOptions = {}): string {
+  const precision = options.precision ?? 0;
+  const v = options.fraction ? value * 100 : value;
+  if (!Number.isFinite(v)) return Number.isNaN(v) ? "NaN%" : v > 0 ? "∞%" : "-∞%";
+  return `${v.toFixed(precision)}%`;
+}
+
+export interface FixedNumberOptions {
+  precision?: number;
+  /** Optional unit suffix (e.g. `" ms"`). */
+  unit?: string;
+}
+
+/** Plain `value.toFixed(precision)` plus optional unit. Useful for axes. */
+export function fixed(value: number, options: FixedNumberOptions = {}): string {
+  const precision = options.precision ?? 0;
+  if (!Number.isFinite(value)) return Number.isNaN(value) ? "NaN" : value > 0 ? "∞" : "-∞";
+  return `${value.toFixed(precision)}${options.unit ?? ""}`;
+}

package/src/grammar/accessibility.d.ts

@@ -0,0 +1,147 @@
+import { type BlendSpace, type Color } from "insomni";
+import type { Theme } from "./theme.ts";
+export type AccessibilityMode = "auto-color" | "outline" | "shadow" | "none";
+export type ContrastMetric = "wcag" | "apca";
+export interface Accessibility {
+    /**
+     * Master switch. When `false`, `resolveTextColor` never alters colors —
+     * but if `warn` is also true it logs the failing site once per session so
+     * authors can see what would have been fixed.
+     */
+    enabled: boolean;
+    /**
+     * Which contrast metric to enforce.
+     *
+     * `"apca"` (default) uses APCA Lc — perceptually uniform and
+     * polarity-aware, so equalizing produces labels that read with the same
+     * weight whether they sit on a dark or a light cell.
+     *
+     * `"wcag"` uses the WCAG 2.1 ratio formula. Kept for backwards
+     * compatibility; equalizing on WCAG ratio looks visually unbalanced
+     * across polarities.
+     */
+    metric: ContrastMetric;
+    /**
+     * WCAG-mode target. `"AA"` = 4.5:1 normal / 3:1 large; `"AAA"` = 7:1 / 4.5:1.
+     * A raw number sets an absolute minimum ratio (1–21) applied to all text
+     * regardless of size. Ignored when `metric === "apca"`.
+     */
+    wcagLevel: "AA" | "AAA" | number;
+    /**
+     * APCA-mode target |Lc|. `"auto"` (default) looks up the recommended
+     * minimum from APCA's font/weight table for each site (typical body text
+     * lands around Lc 75–90). A raw number applies a single |Lc| floor to
+     * every site. Ignored when `metric === "wcag"`.
+     */
+    apcaTarget: number | "auto";
+    /**
+     * How to fix low-contrast text. `auto-color` nudges the color toward an
+     * accessible shade preserving hue/saturation. `outline` / `shadow` are
+     * reserved API hooks — both currently degrade to `auto-color` since the
+     * SDF text pipeline doesn't render text effects yet. `none` leaves text
+     * untouched (and warns when `warn` is on).
+     */
+    mode: AccessibilityMode;
+    /** Whether to console.warn on contrast failures the system isn't fixing. */
+    warn: boolean;
+    /**
+     * When true, every *mark* label (geom-rendered, sitting on a data-driven
+     * fill) is normalized to *exactly* the target contrast — not just `>=`.
+     * Equalizing prevents cells with high contrast from visually outweighing
+     * neighbors. Hue and saturation are preserved; only lightness shifts.
+     *
+     * Chrome text (titles, axis, legend) skips this — those sit on the
+     * panel background and equalizing them just dims legible chrome.
+     */
+    equalize: boolean;
+    /**
+     * How strongly the auto-fixer pulls toward colors already in the theme.
+     * `0` keeps the original hue/sat untouched. `1` snaps to the nearest
+     * passing theme accent. Intermediate values blend in `blendSpace`,
+     * keeping the label feeling "of the same family" as the chart's palette.
+     *
+     * The pull is only applied when at least one accent independently meets
+     * the contrast target — biasing toward an unreadable accent would defeat
+     * the fix. When `equalize` is on, the L-channel is re-fit after the blend
+     * so the final contrast still lands at the target.
+     */
+    themeBias: number;
+    /**
+     * Optional explicit accent palette for the bias. When unset, the
+     * resolver derives accents from the active theme (text/title/legend
+     * colors plus a sample of the categorical palette).
+     */
+    accents?: readonly Color[];
+    /**
+     * Color space used for the theme-bias blend. Defaults to `"oklch"` —
+     * perceptually uniform with hue preserved along the blend.
+     */
+    blendSpace: BlendSpace;
+}
+export declare const DEFAULT_ACCESSIBILITY: Accessibility;
+/**
+ * Stub for SDF text effects. Setting these on the theme today has no visual
+ * effect — the renderer will pick them up once outline/shadow are wired into
+ * the text pipeline. Kept on the public API so call sites and themes can
+ * declare intent now without a follow-up breaking change.
+ */
+export interface TextEffects {
+    outline?: {
+        color: Color;
+        width: number;
+    };
+    shadow?: {
+        color: Color;
+        blur?: number;
+        dx?: number;
+        dy?: number;
+    };
+}
+/** Test helper — clears the dedupe cache so repeat warnings fire again. */
+export declare function _resetAccessibilityWarnings(): void;
+/**
+ * Compute a layer-wide equalize target — the largest |contrast| the worst
+ * cell in `backgrounds` can achieve from a black or white label. Used by
+ * geoms that want every label normalized to the same readable level even
+ * if that means muting high-contrast cells.
+ *
+ * Returns `null` when the metric/policy doesn't equalize (so callers can
+ * skip the pre-pass cheaply).
+ */
+export declare function layerEqualizeTarget(theme: Theme, backgrounds: readonly Color[]): number | null;
+export interface ResolveTextColorOptions {
+    /** Font size in CSS pixels. */
+    fontSizePx: number;
+    /** Treat the text as bold (affects WCAG large-text and APCA weight lookup). */
+    bold?: boolean;
+    /**
+     * Short label identifying the draw site (e.g. `"axis-label"`,
+     * `"tile-label"`). Used to namespace dedupe keys for warnings.
+     */
+    site: string;
+    /**
+     * Whether this site sits on a *data-driven* background (mark fills,
+     * heatmap cells) versus chrome on the panel background. `equalize`
+     * normalization applies only to mark sites — chrome text always sits on
+     * the same panel background, so equalizing it would just lower legible
+     * titles/axis/legend text down toward the contrast floor for no gain.
+     * Default `false`.
+     */
+    markLabel?: boolean;
+    /**
+     * Override the engine-computed target. When set, the resolver uses this
+     * value instead of the font/level lookup. Used by geoms that need to
+     * coordinate a layer-wide equalize floor (e.g. tile pulls every label
+     * down to the worst cell's max-achievable contrast so the layer reads
+     * uniformly, instead of saturating each label at its own per-cell max).
+     */
+    targetOverride?: number;
+    /** @internal — APCA polarity, computed inside the resolver. */
+    _apcaReverse?: boolean;
+}
+/**
+ * Resolve the actual color that should be drawn for a piece of text given
+ * the requested foreground, the known background, and the chart's
+ * accessibility policy. Pure — does not draw anything.
+ */
+export declare function resolveTextColor(fg: Color, bg: Color, theme: Theme, opts: ResolveTextColorOptions): Color;