@ggts-sh/spec 0.43.0

package/src/generated/stat-reference-data.ts

@@ -0,0 +1,339 @@
+/**
+ * AUTO-GENERATED by scripts/gen-reference-catalogs.ts — do not edit by hand.
+ * Regenerate: bun run reference:catalogs:gen
+ *
+ * STAT_REFERENCE — per-stat API docs.
+ */
+export const STAT_REFERENCE_DATA = {
+  identity: {
+    name: "identity",
+    slug: "identity",
+    summary:
+      "Pass rows through unchanged. Default for most geoms: each mapped row becomes one mark with no aggregation.",
+    generatedColumns: [],
+    compatibleGeoms: [
+      "point",
+      "line",
+      "path",
+      "col",
+      "area",
+      "rule",
+      "hline",
+      "vline",
+      "text",
+      "label",
+      "errorbar",
+      "linerange",
+      "pointrange",
+      "crossbar",
+      "rect",
+      "tile",
+      "raster",
+      "ribbon",
+      "segment",
+      "polygon",
+      "abline",
+      "curve",
+      "map",
+      "blank",
+      "jitter",
+      "spoke",
+      "rug",
+      "step",
+    ],
+    defaultForGeoms: [
+      "point",
+      "line",
+      "path",
+      "col",
+      "area",
+      "rule",
+      "hline",
+      "vline",
+      "text",
+      "label",
+      "errorbar",
+      "linerange",
+      "pointrange",
+      "crossbar",
+      "rect",
+      "tile",
+      "raster",
+      "ribbon",
+      "segment",
+      "polygon",
+      "abline",
+      "curve",
+      "map",
+      "blank",
+      "jitter",
+      "spoke",
+      "rug",
+      "step",
+    ],
+  },
+  unique: {
+    name: "unique",
+    slug: "unique",
+    summary:
+      "Keep one row per distinct mapped (x, y) pair (and group). Use when duplicate coordinates would overplot; default for none.",
+    generatedColumns: [],
+    compatibleGeoms: [
+      "point",
+      "line",
+      "path",
+      "col",
+      "area",
+      "rule",
+      "text",
+      "errorbar",
+      "rect",
+      "ribbon",
+      "segment",
+    ],
+    defaultForGeoms: [],
+  },
+  manual: {
+    name: "manual",
+    slug: "manual",
+    summary:
+      "Author-supplied after_stat values via params — skip automatic transforms when you already computed summaries.",
+    generatedColumns: [],
+    compatibleGeoms: ["point", "line", "path"],
+    defaultForGeoms: [],
+  },
+  connect: {
+    name: "connect",
+    slug: "connect",
+    summary:
+      "Expand successive points into connection vertices (linear, hv, vh, mid) for stepped or path-style joins between observations.",
+    generatedColumns: [],
+    compatibleGeoms: ["line", "path"],
+    defaultForGeoms: [],
+  },
+  count: {
+    name: "count",
+    slug: "count",
+    summary:
+      "Count rows (or sum weights) per distinct x within each group. Default for geom_bar; publishes after_stat count.",
+    generatedColumns: ["count"],
+    compatibleGeoms: ["bar"],
+    defaultForGeoms: ["bar"],
+  },
+  bin: {
+    name: "bin",
+    slug: "bin",
+    summary:
+      "Bin continuous x into histogram breaks. Publishes count, density, ncount, and ndensity; default for histogram and freqpoly.",
+    generatedColumns: ["count", "density", "ncount", "ndensity"],
+    compatibleGeoms: ["line", "bar", "histogram", "freqpoly"],
+    defaultForGeoms: ["histogram", "freqpoly"],
+  },
+  bin_hex: {
+    name: "bin_hex",
+    slug: "bin_hex",
+    summary:
+      "Hexagonal 2D binning over continuous x and y. Publishes count/density columns for geom_hex heatmaps.",
+    generatedColumns: ["count", "density", "ncount", "ndensity"],
+    compatibleGeoms: ["hex"],
+    defaultForGeoms: ["hex"],
+  },
+  bin_2d: {
+    name: "bin_2d",
+    slug: "bin_2d",
+    summary:
+      "Rectangular 2D binning over continuous x and y. Publishes count/density and bin edges for geom_bin_2d tiles.",
+    generatedColumns: ["count", "density", "ncount", "ndensity"],
+    compatibleGeoms: ["bin_2d"],
+    defaultForGeoms: ["bin_2d"],
+  },
+  smooth: {
+    name: "smooth",
+    slug: "smooth",
+    summary:
+      "Fit a smoother (lm or loess) and evaluate along x. Publishes y, ymin, ymax, and se; default for geom_smooth.",
+    generatedColumns: ["y", "ymin", "ymax", "se"],
+    compatibleGeoms: ["smooth"],
+    defaultForGeoms: ["smooth"],
+  },
+  quantile: {
+    name: "quantile",
+    slug: "quantile",
+    summary:
+      "Estimate conditional quantiles of y given x. Publishes y at each requested probability; default for geom_quantile.",
+    generatedColumns: ["y"],
+    compatibleGeoms: ["quantile"],
+    defaultForGeoms: ["quantile"],
+  },
+  boxplot: {
+    name: "boxplot",
+    slug: "boxplot",
+    summary:
+      "Five-number summary per group (hinges and whiskers). Publishes ymin, lower, middle, upper, ymax; default for geom_boxplot.",
+    generatedColumns: ["ymin", "lower", "middle", "upper", "ymax"],
+    compatibleGeoms: ["boxplot"],
+    defaultForGeoms: ["boxplot"],
+  },
+  density: {
+    name: "density",
+    slug: "density",
+    summary:
+      "1D Gaussian kernel density estimate along x. Publishes density, count, scaled, and ndensity; default for geom_density.",
+    generatedColumns: ["density", "count", "scaled", "ndensity"],
+    compatibleGeoms: ["density"],
+    defaultForGeoms: ["density"],
+  },
+  summary: {
+    name: "summary",
+    slug: "summary",
+    summary:
+      "Collapse each discrete-x group to one summary (default mean ± se). Publishes y, ymin, ymax for error-style geoms.",
+    generatedColumns: ["y", "ymin", "ymax"],
+    compatibleGeoms: ["errorbar", "linerange", "pointrange", "crossbar"],
+    defaultForGeoms: [],
+  },
+  sum: {
+    name: "sum",
+    slug: "sum",
+    summary:
+      "Count overlapping points at each (x, y) cell for geom_count. Publishes n and prop (not y).",
+    generatedColumns: ["n", "prop"],
+    compatibleGeoms: ["point", "count"],
+    defaultForGeoms: ["count"],
+  },
+  ydensity: {
+    name: "ydensity",
+    slug: "ydensity",
+    summary:
+      "Kernel density along y for violin shapes. Publishes density, count, scaled, violinwidth, and y; default for geom_violin.",
+    generatedColumns: ["density", "count", "scaled", "violinwidth", "y"],
+    compatibleGeoms: ["violin"],
+    defaultForGeoms: ["violin"],
+  },
+  function: {
+    name: "function",
+    slug: "function",
+    summary:
+      "Evaluate a pure function on an x grid. Publishes y; default for geom_function when no data rows drive the mark.",
+    generatedColumns: ["y"],
+    compatibleGeoms: ["function"],
+    defaultForGeoms: ["function"],
+  },
+  ecdf: {
+    name: "ecdf",
+    slug: "ecdf",
+    summary:
+      "Empirical cumulative distribution F̂(x). Publishes ecdf; pair with step or path geoms for CDF plots.",
+    generatedColumns: ["ecdf"],
+    compatibleGeoms: ["line"],
+    defaultForGeoms: [],
+  },
+  summary_bin: {
+    name: "summary_bin",
+    slug: "summary_bin",
+    summary:
+      "Bin continuous x, then summarize y in each bin (mean ± se by default). Publishes y, ymin, ymax for binned summaries.",
+    generatedColumns: ["y", "ymin", "ymax"],
+    compatibleGeoms: ["point", "line", "errorbar"],
+    defaultForGeoms: [],
+  },
+  summary_rolling: {
+    name: "summary_rolling",
+    slug: "summary_rolling",
+    summary:
+      "Centered rolling window over continuous x (params.window, in x units): summarize y per (group, unique x). Partial windows at the ends are kept. Publishes y.",
+    generatedColumns: ["y"],
+    compatibleGeoms: ["point", "line"],
+    defaultForGeoms: [],
+  },
+  contour: {
+    name: "contour",
+    slug: "contour",
+    summary:
+      "Marching-squares isolines over a regular x×y×z grid. Publishes level; default for geom_contour.",
+    generatedColumns: ["level"],
+    compatibleGeoms: ["contour"],
+    defaultForGeoms: ["contour"],
+  },
+  align: {
+    name: "align",
+    slug: "align",
+    summary:
+      "Interpolate series onto a shared x grid so continuous-x stacks and overlays line up (stack-friendly zeros outside range).",
+    generatedColumns: [],
+    compatibleGeoms: ["line", "area"],
+    defaultForGeoms: [],
+  },
+  density_2d: {
+    name: "density_2d",
+    slug: "density_2d",
+    summary:
+      "Bivariate KDE with isolines. Publishes level and density; default for geom_density_2d.",
+    generatedColumns: ["level", "density"],
+    compatibleGeoms: ["density_2d"],
+    defaultForGeoms: ["density_2d"],
+  },
+  density_2d_filled: {
+    name: "density_2d_filled",
+    slug: "density_2d_filled",
+    summary:
+      "Bivariate KDE with closed density rings for filled contours. Publishes level and density; default for geom_density_2d_filled.",
+    generatedColumns: ["level", "density"],
+    compatibleGeoms: ["density_2d_filled"],
+    defaultForGeoms: ["density_2d_filled"],
+  },
+  bindot: {
+    name: "bindot",
+    slug: "bindot",
+    summary:
+      "Histodot binning for geom_dotplot: one stack position per observation. Publishes stackpos (and bin occupancy).",
+    generatedColumns: ["stackpos"],
+    compatibleGeoms: ["dotplot"],
+    defaultForGeoms: ["dotplot"],
+  },
+  ellipse: {
+    name: "ellipse",
+    slug: "ellipse",
+    summary:
+      "Confidence ellipse over bivariate points (level and type from params). Passes geometry suited to path/polygon-style marks.",
+    generatedColumns: [],
+    compatibleGeoms: ["path"],
+    defaultForGeoms: [],
+  },
+  sf: {
+    name: "sf",
+    slug: "sf",
+    summary:
+      "Simple-features geometry expansion for geom_sf: multiparts and holes become drawable rings without after_stat columns.",
+    generatedColumns: [],
+    compatibleGeoms: ["sf"],
+    defaultForGeoms: ["sf"],
+  },
+  sf_coordinates: {
+    name: "sf_coordinates",
+    slug: "sf_coordinates",
+    summary:
+      "Label anchors from SF geometries for geom_sf_text and geom_sf_label (one point per feature or part).",
+    generatedColumns: [],
+    compatibleGeoms: ["sf_text", "sf_label"],
+    defaultForGeoms: ["sf_text", "sf_label"],
+  },
+  qq: {
+    name: "qq",
+    slug: "qq",
+    summary:
+      "Sample vs theoretical quantiles for Q–Q plots. Publishes sample and theoretical; default for geom_qq.",
+    generatedColumns: ["sample", "theoretical"],
+    compatibleGeoms: ["qq"],
+    defaultForGeoms: ["qq"],
+  },
+  qq_line: {
+    name: "qq_line",
+    slug: "qq_line",
+    summary:
+      "Reference line through Q–Q sample/theoretical quantiles. Publishes sample and theoretical; default for geom_qq_line.",
+    generatedColumns: ["sample", "theoretical"],
+    compatibleGeoms: ["qq_line"],
+    defaultForGeoms: ["qq_line"],
+  },
+} as const;

package/src/geom-params-build.ts

@@ -0,0 +1,92 @@
+/**
+ * GEOM_PARAM_KEYS builder (SpecDeclarations walk). Gen-only:
+ * `scripts/gen-reference-catalogs.ts`. Runtime uses generated/geom-param-keys.ts.
+ */
+import type { TSchema } from "typebox";
+
+import { KNOWN_GEOMS, type GeomName } from "./schema-catalog.js";
+import { SpecDeclarations } from "./schema-declarations.js";
+
+type SpecDecl = typeof SpecDeclarations;
+type DeclKey = keyof SpecDecl;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** Depth-first `$ref` string, if present. */
+function findRef(node: unknown, depth = 0): string | undefined {
+  if (!isRecord(node) || depth > 8) return undefined;
+  const ref = node["$ref"];
+  if (typeof ref === "string") return ref;
+  for (const child of Object.values(node)) {
+    const found = findRef(child, depth + 1);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+/**
+ * Resolve a SpecDeclarations key through `$ref` aliases to a schema that
+ * may carry `properties`. Throws on missing keys or cycles.
+ */
+function resolveDeclaration(name: string, seen: Set<string> = new Set()): TSchema {
+  if (seen.has(name)) {
+    throw new Error(`GEOM_PARAM_KEYS: cyclic SpecDeclarations ref involving "${name}"`);
+  }
+  if (!(name in SpecDeclarations)) {
+    throw new Error(`GEOM_PARAM_KEYS: SpecDeclarations has no entry "${name}"`);
+  }
+  seen.add(name);
+  const schema = SpecDeclarations[name as DeclKey] as TSchema & { $ref?: string };
+  if (typeof schema.$ref === "string") {
+    return resolveDeclaration(schema.$ref, seen);
+  }
+  return schema;
+}
+
+/** Params type name for a geom (e.g. "point" → "PointParams"), or null if none. */
+function paramsTypeNameForGeom(geom: GeomName): string | null {
+  for (const key of Object.keys(SpecDeclarations) as DeclKey[]) {
+    // Layer schemas are *Layer (PointLayer, …).
+    if (!key.endsWith("Layer")) continue;
+    const layer = SpecDeclarations[key] as TSchema & {
+      properties?: { geom?: { const?: string }; params?: unknown };
+    };
+    const geomConst = layer.properties?.geom?.const;
+    if (geomConst !== geom) continue;
+    const paramsNode = layer.properties?.params;
+    if (paramsNode === undefined) {
+      throw new Error(`GEOM_PARAM_KEYS: layer ${key} has no params field for geom "${geom}"`);
+    }
+    const ref = findRef(paramsNode);
+    if (ref === undefined) {
+      throw new Error(`GEOM_PARAM_KEYS: layer ${key} params has no $ref for geom "${geom}"`);
+    }
+    return ref;
+  }
+  throw new Error(`GEOM_PARAM_KEYS: no *Layer schema with geom const "${geom}"`);
+}
+
+function paramKeysForGeom(geom: GeomName): readonly string[] {
+  const paramsName = paramsTypeNameForGeom(geom);
+  if (paramsName === null) return Object.freeze([]);
+  const resolved = resolveDeclaration(paramsName) as TSchema & {
+    properties?: Record<string, unknown>;
+  };
+  const props = resolved.properties;
+  if (props === undefined) {
+    // Type.Object({}) still has properties: {}; a bare alias without properties
+    // after ref resolution is treated as empty.
+    return Object.freeze([]);
+  }
+  return Object.freeze(Object.keys(props));
+}
+
+export function buildGeomParamKeys(): Readonly<Record<GeomName, readonly string[]>> {
+  const out = {} as Record<GeomName, readonly string[]>;
+  for (const geom of KNOWN_GEOMS) {
+    out[geom] = paramKeysForGeom(geom);
+  }
+  return Object.freeze(out);
+}

package/src/geom-params.ts

@@ -0,0 +1,14 @@
+/**
+ * GEOM_PARAM_KEYS (#1039) — param-key whitelist per geom.
+ *
+ * Precomputed from SpecDeclarations (`scripts/gen-reference-catalogs.ts`) so
+ * createGeomLayer never loads TypeBox. Regenerate after schema param changes.
+ */
+import type { GeomName } from "./schema-catalog.js";
+import { GEOM_PARAM_KEYS_DATA } from "./generated/geom-param-keys.js";
+
+/**
+ * Param property names per geom, derived from SpecDeclarations at gen time.
+ * Empty array means the geom has no params object properties (e.g. blank).
+ */
+export const GEOM_PARAM_KEYS: Readonly<Record<GeomName, readonly string[]>> = GEOM_PARAM_KEYS_DATA;