insomni-plot 0.1.0-alpha.0

package/src/colors.ts

@@ -0,0 +1,486 @@
+import { cssHex, lerpInSpace, type BlendSpace, type Color } from "insomni";
+import { clamp } from "./scales.ts";
+
+export interface ContinuousPalette {
+  (t: number): Color;
+  readonly kind: "continuous";
+  readonly stops: readonly Color[];
+  /** Color space used to interpolate between adjacent stops. */
+  readonly blendSpace: BlendSpace;
+  /**
+   * Return a new palette with the same stops but interpolating in the given
+   * space. The original is unchanged. Cheap — palettes are stateless.
+   */
+  withBlendSpace(space: BlendSpace): ContinuousPalette;
+}
+
+export interface CategoricalPalette {
+  (index: number): Color;
+  readonly kind: "categorical";
+  readonly colors: readonly Color[];
+}
+
+export function colorScale(
+  palette: ContinuousPalette,
+  domain: readonly [number, number],
+): (value: number) => Color;
+export function colorScale<Domain>(
+  palette: CategoricalPalette,
+  domain: readonly Domain[],
+): (value: Domain) => Color;
+export function colorScale<Domain>(
+  palette: ContinuousPalette | CategoricalPalette,
+  domain: readonly [number, number] | readonly Domain[],
+): (value: number | Domain) => Color {
+  if (
+    Array.isArray(domain) &&
+    domain.length === 2 &&
+    typeof domain[0] === "number" &&
+    typeof domain[1] === "number"
+  ) {
+    const [d0, d1] = domain;
+    if (palette.kind === "continuous") {
+      return (value: number | Domain) => {
+        const numeric = value as number;
+        const t = d0 === d1 ? 0.5 : (numeric - d0) / (d1 - d0);
+        return palette(t);
+      };
+    }
+
+    const colors = palette.colors;
+    return (value: number | Domain) => {
+      const numeric = value as number;
+      const t = d0 === d1 ? 0 : (numeric - d0) / (d1 - d0);
+      const index = Math.round(clamp(t, 0, 1) * Math.max(colors.length - 1, 0));
+      return colors[index] ?? colors[colors.length - 1]!;
+    };
+  }
+
+  const categories = [...(domain as readonly Domain[])];
+  const index = new Map<Domain, number>();
+  for (let offset = 0; offset < categories.length; offset++) {
+    index.set(categories[offset]!, offset);
+  }
+
+  if (palette.kind === "categorical") {
+    return (value: number | Domain) => palette(index.get(value as Domain) ?? 0);
+  }
+
+  return (value: number | Domain) => {
+    const offset = index.get(value as Domain) ?? 0;
+    const t = categories.length <= 1 ? 0.5 : offset / (categories.length - 1);
+    return palette(t);
+  };
+}
+
+function paletteFromStops(stops: readonly Color[], space: BlendSpace): ContinuousPalette {
+  const palette = ((t: number) => {
+    const normalized = clamp(t, 0, 1);
+    if (stops.length === 1) return stops[0]!;
+    const scaled = normalized * (stops.length - 1);
+    const index = Math.min(Math.floor(scaled), stops.length - 2);
+    const localT = scaled - index;
+    return lerpInSpace(stops[index]!, stops[index + 1]!, localT, space);
+  }) as ContinuousPalette;
+
+  Object.defineProperties(palette, {
+    kind: { value: "continuous", enumerable: true },
+    stops: { value: stops, enumerable: true },
+    blendSpace: { value: space, enumerable: true },
+    withBlendSpace: {
+      value: (next: BlendSpace) => (next === space ? palette : paletteFromStops(stops, next)),
+      enumerable: false,
+    },
+  });
+
+  return palette;
+}
+
+function createContinuousPalette(
+  hexStops: readonly string[],
+  options: { blendSpace?: BlendSpace } = {},
+): ContinuousPalette {
+  // Default to sRGB so the built-in palettes (viridis, magma, …) keep the
+  // exact gradient their authors hand-tuned. Charts upgrade to OKLch via
+  // `theme.paletteBlendSpace` so consumers get the perceptual blend by
+  // default without breaking standalone palette use.
+  const space = options.blendSpace ?? "srgb";
+  const stops = hexStops.map((value) => cssHex(value));
+  return paletteFromStops(stops, space);
+}
+
+function createCategoricalPalette(hexColors: readonly string[]): CategoricalPalette {
+  const colors = hexColors.map((value) => cssHex(value));
+  const palette = ((index: number) => {
+    if (colors.length === 0) {
+      throw new Error("Categorical palettes must contain at least one color.");
+    }
+    const resolved = ((Math.trunc(index) % colors.length) + colors.length) % colors.length;
+    return colors[resolved]!;
+  }) as CategoricalPalette;
+
+  Object.defineProperties(palette, {
+    kind: { value: "categorical", enumerable: true },
+    colors: { value: colors, enumerable: true },
+  });
+
+  return palette;
+}
+
+export const viridis = createContinuousPalette([
+  "#440154",
+  "#414487",
+  "#2a788e",
+  "#22a884",
+  "#7ad151",
+  "#fde725",
+]);
+
+export const plasma = createContinuousPalette([
+  "#0d0887",
+  "#5b02a3",
+  "#9a179b",
+  "#cb4679",
+  "#ed7953",
+  "#fdb42f",
+  "#f0f921",
+]);
+
+export const inferno = createContinuousPalette([
+  "#000004",
+  "#320a5a",
+  "#781b6c",
+  "#bb3654",
+  "#ed6925",
+  "#fbb41a",
+  "#fcffa4",
+]);
+
+export const magma = createContinuousPalette([
+  "#000004",
+  "#221150",
+  "#5f187f",
+  "#982d80",
+  "#d3436e",
+  "#f8765c",
+  "#fcfdbf",
+]);
+
+export const cividis = createContinuousPalette([
+  "#00204c",
+  "#2e3f6d",
+  "#575d6d",
+  "#7d7c5c",
+  "#a59c46",
+  "#d5be38",
+  "#ffe945",
+]);
+
+export const coolwarm = createContinuousPalette([
+  "#3b4cc0",
+  "#6f92f3",
+  "#aac7fd",
+  "#dddcdc",
+  "#f7b89c",
+  "#e7745b",
+  "#b40426",
+]);
+
+export const rdbu = createContinuousPalette([
+  "#67001f",
+  "#b2182b",
+  "#d6604d",
+  "#fddbc7",
+  "#f7f7f7",
+  "#d1e5f0",
+  "#4393c3",
+  "#2166ac",
+  "#053061",
+]);
+
+export const spectral = createContinuousPalette([
+  "#9e0142",
+  "#d53e4f",
+  "#f46d43",
+  "#fdae61",
+  "#fee08b",
+  "#ffffbf",
+  "#e6f598",
+  "#abdda4",
+  "#66c2a5",
+  "#3288bd",
+  "#5e4fa2",
+]);
+
+export const tableau10 = createCategoricalPalette([
+  "#4e79a7",
+  "#f28e2b",
+  "#e15759",
+  "#76b7b2",
+  "#59a14f",
+  "#edc948",
+  "#b07aa1",
+  "#ff9da7",
+  "#9c755f",
+  "#bab0ab",
+]);
+
+export const category10 = createCategoricalPalette([
+  "#1f77b4",
+  "#ff7f0e",
+  "#2ca02c",
+  "#d62728",
+  "#9467bd",
+  "#8c564b",
+  "#e377c2",
+  "#7f7f7f",
+  "#bcbd22",
+  "#17becf",
+]);
+
+export const pastel = createCategoricalPalette([
+  "#fbb4ae",
+  "#b3cde3",
+  "#ccebc5",
+  "#decbe4",
+  "#fed9a6",
+  "#ffffcc",
+  "#e5d8bd",
+  "#fddaec",
+]);
+
+// ---------------------------------------------------------------------------
+// Categorical — ColorBrewer
+// ---------------------------------------------------------------------------
+
+export const set1 = createCategoricalPalette([
+  "#e41a1c",
+  "#377eb8",
+  "#4daf4a",
+  "#984ea3",
+  "#ff7f00",
+  "#ffff33",
+  "#a65628",
+  "#f781bf",
+  "#999999",
+]);
+
+export const set2 = createCategoricalPalette([
+  "#66c2a5",
+  "#fc8d62",
+  "#8da0cb",
+  "#e78ac3",
+  "#a6d854",
+  "#ffd92f",
+  "#e5c494",
+  "#b3b3b3",
+]);
+
+export const set3 = createCategoricalPalette([
+  "#8dd3c7",
+  "#ffffb3",
+  "#bebada",
+  "#fb8072",
+  "#80b1d3",
+  "#fdb462",
+  "#b3de69",
+  "#fccde5",
+  "#d9d9d9",
+  "#bc80bd",
+  "#ccebc5",
+  "#ffed6f",
+]);
+
+export const dark2 = createCategoricalPalette([
+  "#1b9e77",
+  "#d95f02",
+  "#7570b3",
+  "#e7298a",
+  "#66a61e",
+  "#e6ab02",
+  "#a6761d",
+  "#666666",
+]);
+
+export const accent = createCategoricalPalette([
+  "#7fc97f",
+  "#beaed4",
+  "#fdc086",
+  "#ffff99",
+  "#386cb0",
+  "#f0027f",
+  "#bf5b17",
+  "#666666",
+]);
+
+export const paired = createCategoricalPalette([
+  "#a6cee3",
+  "#1f78b4",
+  "#b2df8a",
+  "#33a02c",
+  "#fb9a99",
+  "#e31a1c",
+  "#fdbf6f",
+  "#ff7f00",
+  "#cab2d6",
+  "#6a3d9a",
+  "#ffff99",
+  "#b15928",
+]);
+
+// ---------------------------------------------------------------------------
+// Sequential single-hue — ColorBrewer
+// ---------------------------------------------------------------------------
+
+export const blues = createContinuousPalette([
+  "#f7fbff",
+  "#deebf7",
+  "#c6dbef",
+  "#9ecae1",
+  "#6baed6",
+  "#4292c6",
+  "#2171b5",
+  "#08519c",
+  "#08306b",
+]);
+
+export const greens = createContinuousPalette([
+  "#f7fcf5",
+  "#e5f5e0",
+  "#c7e9c0",
+  "#a1d99b",
+  "#74c476",
+  "#41ab5d",
+  "#238b45",
+  "#006d2c",
+  "#00441b",
+]);
+
+export const oranges = createContinuousPalette([
+  "#fff5eb",
+  "#fee6ce",
+  "#fdd0a2",
+  "#fdae6b",
+  "#fd8d3c",
+  "#f16913",
+  "#d94801",
+  "#a63603",
+  "#7f2704",
+]);
+
+export const reds = createContinuousPalette([
+  "#fff5f0",
+  "#fee0d2",
+  "#fcbba1",
+  "#fc9272",
+  "#fb6a4a",
+  "#ef3b2c",
+  "#cb181d",
+  "#a50f15",
+  "#67000d",
+]);
+
+export const purples = createContinuousPalette([
+  "#fcfbfd",
+  "#efedf5",
+  "#dadaeb",
+  "#bcbddc",
+  "#9e9ac8",
+  "#807dba",
+  "#6a51a3",
+  "#54278f",
+  "#3f007d",
+]);
+
+export const greys = createContinuousPalette([
+  "#ffffff",
+  "#f0f0f0",
+  "#d9d9d9",
+  "#bdbdbd",
+  "#969696",
+  "#737373",
+  "#525252",
+  "#252525",
+  "#000000",
+]);
+
+// ---------------------------------------------------------------------------
+// Diverging — ColorBrewer
+// ---------------------------------------------------------------------------
+
+export const brbg = createContinuousPalette([
+  "#543005",
+  "#8c510a",
+  "#bf812d",
+  "#dfc27d",
+  "#f6e8c3",
+  "#f5f5f5",
+  "#c7eae5",
+  "#80cdc1",
+  "#35978f",
+  "#01665e",
+  "#003c30",
+]);
+
+export const prgn = createContinuousPalette([
+  "#40004b",
+  "#762a83",
+  "#9970ab",
+  "#c2a5cf",
+  "#e7d4e8",
+  "#f7f7f7",
+  "#d9f0d3",
+  "#a6dba0",
+  "#5aae61",
+  "#1b7837",
+  "#00441b",
+]);
+
+export const piyg = createContinuousPalette([
+  "#8e0152",
+  "#c51b7d",
+  "#de77ae",
+  "#f1b6da",
+  "#fde0ef",
+  "#f7f7f7",
+  "#e6f5d0",
+  "#b8e186",
+  "#7fbc41",
+  "#4d9221",
+  "#276419",
+]);
+
+export const puor = createContinuousPalette([
+  "#7f3b08",
+  "#b35806",
+  "#e08214",
+  "#fdb863",
+  "#fee0b6",
+  "#f7f7f7",
+  "#d8daeb",
+  "#b2abd2",
+  "#8073ac",
+  "#542788",
+  "#2d004b",
+]);
+
+// ---------------------------------------------------------------------------
+// Custom palette factories — for users who want their own gradients/sets
+// without re-implementing the closure plumbing.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a continuous palette from an arbitrary list of CSS hex stops.
+ * Stops are evenly spaced; sample with `palette(t)` where `t ∈ [0, 1]`.
+ */
+export function continuousPalette(hexStops: readonly string[]): ContinuousPalette {
+  return createContinuousPalette(hexStops);
+}
+
+/**
+ * Build a categorical palette from an arbitrary list of CSS hex colors.
+ * Indices wrap modulo length, so `palette(N)` always returns a valid color.
+ */
+export function categoricalPalette(hexColors: readonly string[]): CategoricalPalette {
+  return createCategoricalPalette(hexColors);
+}