insomni-plot 0.1.0-alpha.0

package/src/grammar/palettes.d.ts

@@ -0,0 +1,54 @@
+import { type PointShapeKind } from "../marks.ts";
+import { type CategoricalPalette } from "../colors.ts";
+/** Built-in categorical palette identifiers supported by `distinguishable`. */
+export type DistinguishableScheme = "category10" | "tableau10" | "set1" | "set2" | "set3" | "dark2" | "paired" | "pastel";
+export interface DistinguishableOptions {
+    /** Per-channel cardinality. Each count must be ≥ 1. */
+    for: {
+        color: number;
+        shape: number;
+    };
+    /**
+     * Categorical palette to source the color palette from. Default
+     * `"category10"`. Pass a `CategoricalPalette` directly for a custom set.
+     */
+    scheme?: DistinguishableScheme | CategoricalPalette;
+    /**
+     * Override the shape pool. Default: `POINT_SHAPE_PALETTE` from `marks`,
+     * which is already ordered for silhouette distinctness.
+     */
+    shapes?: readonly PointShapeKind[];
+}
+export interface DistinguishablePalettes {
+    /**
+     * A categorical palette sliced to exactly `for.color` colors from the
+     * requested scheme. Plug into `scale("color", { palette })`.
+     */
+    color: CategoricalPalette;
+    /**
+     * Shape palette sliced to exactly `for.shape` entries. Plug into
+     * `scale("shape", { palette })`.
+     */
+    shape: readonly PointShapeKind[];
+}
+/**
+ * Build a matched `{ color, shape }` pair sized for the two channels'
+ * cardinalities. Sugar over manual `palette.colors.slice(0, N)` +
+ * `POINT_SHAPE_PALETTE.slice(0, M)` — the goal is one declaration site for
+ * the visual contract of a multi-encoding chart.
+ *
+ * Counts that exceed the source pool wrap modulo length, matching the
+ * default `CategoricalPalette` / scale wrap semantics so the helper never
+ * silently drops categories. (The visual distinction degrades past the pool
+ * size — that's an authoring problem, not a library one — but the runtime
+ * stays consistent with the rest of the scale system.)
+ */
+export declare function distinguishable(options: DistinguishableOptions): DistinguishablePalettes;
+/**
+ * `palettes` namespace — currently the home of `distinguishable`. Future
+ * combinators (legend-paired schemes, perceptual-uniform slicing, …) live
+ * here so the surface stays small and predictable.
+ */
+export declare const palettes: {
+    readonly distinguishable: typeof distinguishable;
+};

package/src/grammar/palettes.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "vite-plus/test";
+
+import { category10, set1, tableau10 } from "../colors.ts";
+import { POINT_SHAPE_PALETTE } from "../marks.ts";
+import { distinguishable, palettes } from "./palettes.ts";
+
+describe("palettes.distinguishable", () => {
+  test("returns the matched color/shape pair sized to the requested counts", () => {
+    const { color, shape } = distinguishable({ for: { color: 4, shape: 3 } });
+    expect(color.kind).toBe("categorical");
+    expect(color.colors.length).toBe(4);
+    expect(shape.length).toBe(3);
+    // First N colors come from category10 (the default scheme).
+    for (let i = 0; i < 4; i++) {
+      expect(color.colors[i]).toEqual(category10.colors[i]);
+    }
+    // Shapes mirror POINT_SHAPE_PALETTE's ordering.
+    for (let i = 0; i < 3; i++) {
+      expect(shape[i]).toBe(POINT_SHAPE_PALETTE[i]);
+    }
+  });
+
+  test("named scheme picks the corresponding built-in palette", () => {
+    const { color } = distinguishable({ for: { color: 3, shape: 1 }, scheme: "tableau10" });
+    for (let i = 0; i < 3; i++) {
+      expect(color.colors[i]).toEqual(tableau10.colors[i]);
+    }
+  });
+
+  test("custom CategoricalPalette passed as scheme is honored", () => {
+    const { color } = distinguishable({ for: { color: 2, shape: 1 }, scheme: set1 });
+    expect(color.colors[0]).toEqual(set1.colors[0]);
+    expect(color.colors[1]).toEqual(set1.colors[1]);
+  });
+
+  test("custom shape pool is honored", () => {
+    const pool = ["square", "diamond"] as const;
+    const { shape } = distinguishable({ for: { color: 1, shape: 2 }, shapes: pool });
+    expect(shape).toEqual(["square", "diamond"]);
+  });
+
+  test("counts that exceed pool size wrap modulo the pool length", () => {
+    const { color, shape } = distinguishable({ for: { color: 12, shape: 14 } });
+    expect(color.colors.length).toBe(12);
+    expect(shape.length).toBe(14);
+    // category10 has 10 colors — index 10 wraps to index 0.
+    expect(color.colors[10]).toEqual(category10.colors[0]);
+    expect(color.colors[11]).toEqual(category10.colors[1]);
+    // POINT_SHAPE_PALETTE has 11 entries — index 11 wraps to index 0.
+    expect(shape[11]).toBe(POINT_SHAPE_PALETTE[0]);
+  });
+
+  test("returned color palette is callable and wraps like the built-ins", () => {
+    const { color } = distinguishable({ for: { color: 3, shape: 1 } });
+    // Modulo-wrap parity with the standard categorical-palette closure.
+    expect(color(0)).toEqual(color.colors[0]);
+    expect(color(3)).toEqual(color.colors[0]);
+    expect(color(-1)).toEqual(color.colors[2]);
+  });
+
+  test("invalid counts throw at construction", () => {
+    expect(() => distinguishable({ for: { color: 0, shape: 1 } })).toThrow(/color/);
+    expect(() => distinguishable({ for: { color: 2, shape: -1 } })).toThrow(/shape/);
+    expect(() => distinguishable({ for: { color: 1.5, shape: 1 } })).toThrow(/color/);
+  });
+
+  test("unknown scheme name throws", () => {
+    expect(() =>
+      distinguishable({
+        for: { color: 2, shape: 1 },
+        // Force an invalid string past the union — surface check on the runtime guard.
+        scheme: "not-a-scheme" as unknown as "category10",
+      }),
+    ).toThrow(/Unknown palette scheme/);
+  });
+
+  test("namespace re-export matches the function export", () => {
+    expect(palettes.distinguishable).toBe(distinguishable);
+  });
+});

package/src/grammar/palettes.ts

@@ -0,0 +1,167 @@
+// ---------------------------------------------------------------------------
+// palettes — categorical encoding combinators
+// ---------------------------------------------------------------------------
+// Companion to the round-1 auto-legend merge: that closes the case where
+// `color` and `shape` encode the *same* dimension. This namespace closes
+// the inverse case — when `color` and `shape` encode *different* dimensions
+// and the consumer wants matched defaults instead of picking ad hoc.
+//
+// `distinguishable({ for: { color: N, shape: M } })` returns a `{ color,
+// shape }` pair: a categorical palette sized for `N` (the first N entries
+// of the requested scheme) and a shape palette sized for `M` (the first M
+// entries of `POINT_SHAPE_PALETTE`, which is already ordered by silhouette
+// distinctness — circle, triangle, square, diamond, …).
+//
+// The helper is sugar, not a heuristic: built-in categorical palettes
+// (`category10`, `tableau10`, `set1`, …) are already authored to maximize
+// inter-color distinction, and `POINT_SHAPE_PALETTE` is already ordered
+// for maximum inter-shape distinction. The win is that callers stop
+// hand-slicing them in module-level boilerplate.
+
+import type { Color } from "insomni";
+import { POINT_SHAPE_PALETTE, type PointShapeKind } from "../marks.ts";
+import {
+  category10,
+  dark2,
+  paired,
+  pastel,
+  set1,
+  set2,
+  set3,
+  tableau10,
+  type CategoricalPalette,
+} from "../colors.ts";
+
+/** Built-in categorical palette identifiers supported by `distinguishable`. */
+export type DistinguishableScheme =
+  | "category10"
+  | "tableau10"
+  | "set1"
+  | "set2"
+  | "set3"
+  | "dark2"
+  | "paired"
+  | "pastel";
+
+const SCHEMES: Record<DistinguishableScheme, CategoricalPalette> = {
+  category10,
+  tableau10,
+  set1,
+  set2,
+  set3,
+  dark2,
+  paired,
+  pastel,
+};
+
+export interface DistinguishableOptions {
+  /** Per-channel cardinality. Each count must be ≥ 1. */
+  for: { color: number; shape: number };
+  /**
+   * Categorical palette to source the color palette from. Default
+   * `"category10"`. Pass a `CategoricalPalette` directly for a custom set.
+   */
+  scheme?: DistinguishableScheme | CategoricalPalette;
+  /**
+   * Override the shape pool. Default: `POINT_SHAPE_PALETTE` from `marks`,
+   * which is already ordered for silhouette distinctness.
+   */
+  shapes?: readonly PointShapeKind[];
+}
+
+export interface DistinguishablePalettes {
+  /**
+   * A categorical palette sliced to exactly `for.color` colors from the
+   * requested scheme. Plug into `scale("color", { palette })`.
+   */
+  color: CategoricalPalette;
+  /**
+   * Shape palette sliced to exactly `for.shape` entries. Plug into
+   * `scale("shape", { palette })`.
+   */
+  shape: readonly PointShapeKind[];
+}
+
+function resolveScheme(
+  scheme: DistinguishableScheme | CategoricalPalette | undefined,
+): CategoricalPalette {
+  if (!scheme) return category10;
+  if (typeof scheme === "string") {
+    const palette = SCHEMES[scheme];
+    if (!palette) {
+      throw new Error(`Unknown palette scheme "${scheme as string}".`);
+    }
+    return palette;
+  }
+  return scheme;
+}
+
+/**
+ * Build a matched `{ color, shape }` pair sized for the two channels'
+ * cardinalities. Sugar over manual `palette.colors.slice(0, N)` +
+ * `POINT_SHAPE_PALETTE.slice(0, M)` — the goal is one declaration site for
+ * the visual contract of a multi-encoding chart.
+ *
+ * Counts that exceed the source pool wrap modulo length, matching the
+ * default `CategoricalPalette` / scale wrap semantics so the helper never
+ * silently drops categories. (The visual distinction degrades past the pool
+ * size — that's an authoring problem, not a library one — but the runtime
+ * stays consistent with the rest of the scale system.)
+ */
+export function distinguishable(options: DistinguishableOptions): DistinguishablePalettes {
+  const colorCount = options.for.color;
+  const shapeCount = options.for.shape;
+  if (!Number.isInteger(colorCount) || colorCount < 1) {
+    throw new Error(`distinguishable: 'for.color' must be an integer ≥ 1 (got ${colorCount}).`);
+  }
+  if (!Number.isInteger(shapeCount) || shapeCount < 1) {
+    throw new Error(`distinguishable: 'for.shape' must be an integer ≥ 1 (got ${shapeCount}).`);
+  }
+  const palette = resolveScheme(options.scheme);
+  const shapePool = options.shapes ?? POINT_SHAPE_PALETTE;
+  if (shapePool.length === 0) {
+    throw new Error("distinguishable: 'shapes' pool must contain at least one shape.");
+  }
+
+  const sourceColors = palette.colors;
+  const colors: Color[] = Array.from({ length: colorCount });
+  for (let i = 0; i < colorCount; i++) {
+    colors[i] = sourceColors[i % sourceColors.length]!;
+  }
+  const colorPalette = categoricalFromColors(colors);
+
+  const shape: PointShapeKind[] = Array.from({ length: shapeCount });
+  for (let i = 0; i < shapeCount; i++) {
+    shape[i] = shapePool[i % shapePool.length]!;
+  }
+
+  return { color: colorPalette, shape };
+}
+
+// Build a CategoricalPalette from already-resolved `Color` objects. Mirrors
+// the closure in `colors.ts`'s `createCategoricalPalette` (which only
+// accepts hex strings publicly). Kept private to this module to avoid
+// growing the public colors surface for a single internal caller.
+function categoricalFromColors(colors: readonly Color[]): CategoricalPalette {
+  if (colors.length === 0) {
+    throw new Error("Categorical palettes must contain at least one color.");
+  }
+  const palette = ((index: number) => {
+    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;
+}
+
+/**
+ * `palettes` namespace — currently the home of `distinguishable`. Future
+ * combinators (legend-paired schemes, perceptual-uniform slicing, …) live
+ * here so the surface stays small and predictable.
+ */
+export const palettes = {
+  distinguishable,
+} as const;