@ggts-sh/spec 0.43.0

package/src/schema-catalog.ts

@@ -0,0 +1,222 @@
+/**
+ * Pipeline catalogs keyed off the schema version: geoms, stats, positions,
+ * channels, edition stamp, and per-geom defaults (normalize fills these).
+ */
+/** Geom names known to this schema version (discriminator values of LayerSpec). */
+export const KNOWN_GEOMS = [
+  "point",
+  "line",
+  "path",
+  "col",
+  "bar",
+  "histogram",
+  "freqpoly",
+  "area",
+  "rule",
+  "hline",
+  "vline",
+  "text",
+  "label",
+  "smooth",
+  "quantile",
+  "boxplot",
+  "density",
+  "errorbar",
+  "linerange",
+  "pointrange",
+  "crossbar",
+  "rect",
+  "tile",
+  "raster",
+  "ribbon",
+  "segment",
+  "count",
+  "violin",
+  "function",
+  "polygon",
+  "hex",
+  "bin_2d",
+  "abline",
+  "curve",
+  "contour",
+  "density_2d",
+  "density_2d_filled",
+  "dotplot",
+  "map",
+  "sf",
+  "sf_text",
+  "sf_label",
+  "blank",
+  "jitter",
+  "spoke",
+  "rug",
+  "step",
+  "qq",
+  "qq_line",
+] as const;
+export type GeomName = (typeof KNOWN_GEOMS)[number];
+
+/**
+ * Convenience geom names normalize() rewrites away. None of these can reach
+ * the render pipeline, so pipeline tables key off {@link NormalizedGeomName}
+ * and the compiler names any geom they forget (#1042).
+ *
+ * Declared before GEOM_ALIASES on purpose: deriving the alias names from that
+ * table's keys and then constraining its values to NormalizedGeomName would be
+ * circular, and the looser constraint would accept an alias pointing at
+ * another alias — which one pass of canonicalGeom() would leave in place.
+ */
+export const ALIAS_GEOMS = ["histogram", "freqpoly", "jitter", "hline", "vline"] as const;
+export type AliasGeomName = (typeof ALIAS_GEOMS)[number];
+
+/** A geom name that can reach the render pipeline (post-normalize). */
+export type NormalizedGeomName = Exclude<GeomName, AliasGeomName>;
+
+/** What each alias rewrites to. Targets are canonical, never another alias. */
+export const GEOM_ALIASES = {
+  histogram: "bar",
+  freqpoly: "line",
+  jitter: "point",
+  hline: "rule",
+  vline: "rule",
+} as const satisfies Record<AliasGeomName, NormalizedGeomName>;
+
+/**
+ * The current DEFAULTS EDITION (Hadley lesson 13: fix accumulated bad
+ * defaults "without breaking existing code"). normalize() stamps this onto
+ * specs that carry no `edition`, freezing which generation of default
+ * aesthetics (theme role tokens, categorical palette) the spec was authored
+ * against. @ggts-sh/core keys its theme/palette default tables by edition,
+ * so when a future edition improves the defaults, already-stamped specs keep
+ * their edition-1 look. Explicit theme/scale settings always win regardless.
+ */
+export const CURRENT_EDITION = 2;
+
+/** Aesthetic channel names known to this schema version. */
+export const CHANNELS = [
+  "x",
+  "y",
+  "color",
+  "fill",
+  "size",
+  "linewidth",
+  "alpha",
+  "shape",
+  "linetype",
+  "group",
+  "label",
+  "weight",
+  "ymin",
+  "ymax",
+  "xmin",
+  "xmax",
+  "xend",
+  "yend",
+  "width",
+  "height",
+  "z",
+  "map_id",
+  "angle",
+  "radius",
+  "sample",
+] as const;
+export type ChannelName = (typeof CHANNELS)[number];
+
+/** Stat names known to this schema version. */
+export const KNOWN_STATS = [
+  "identity",
+  "unique",
+  "manual",
+  "connect",
+  "count",
+  "bin",
+  "bin_hex",
+  "bin_2d",
+  "smooth",
+  "quantile",
+  "boxplot",
+  "density",
+  "summary",
+  "sum",
+  "ydensity",
+  "function",
+  "ecdf",
+  "summary_bin",
+  "summary_rolling",
+  "contour",
+  "align",
+  "density_2d",
+  "density_2d_filled",
+  "bindot",
+  "ellipse",
+  "sf",
+  "sf_coordinates",
+  "qq",
+  "qq_line",
+] as const;
+export type StatName = (typeof KNOWN_STATS)[number];
+
+/** Position names known to this schema version. */
+export const KNOWN_POSITIONS = ["identity", "stack", "fill", "dodge", "jitter", "nudge"] as const;
+export type PositionName = (typeof KNOWN_POSITIONS)[number];
+
+/**
+ * Per-geom pipeline defaults, mirrored from ggplot2 (normalize() fills these):
+ * geom bar counts (stat "count") and stacks; histogram bins and stacks;
+ * freqpoly bins and draws as line (identity position); col/area stack
+ * pre-computed values; boxplot dodges (ggplot2 defaults to dodge2 —
+ * ggts uses plain dodge, decision 0010); jitter aliases to
+ * point+position jitter; hline/vline alias to rule; everything else is
+ * identity/identity.
+ */
+export const GEOM_DEFAULTS: Record<GeomName, { stat: StatName; position: PositionName }> = {
+  point: { stat: "identity", position: "identity" },
+  line: { stat: "identity", position: "identity" },
+  path: { stat: "identity", position: "identity" },
+  col: { stat: "identity", position: "stack" },
+  bar: { stat: "count", position: "stack" },
+  histogram: { stat: "bin", position: "stack" },
+  freqpoly: { stat: "bin", position: "identity" },
+  area: { stat: "identity", position: "stack" },
+  rule: { stat: "identity", position: "identity" },
+  hline: { stat: "identity", position: "identity" },
+  vline: { stat: "identity", position: "identity" },
+  text: { stat: "identity", position: "identity" },
+  label: { stat: "identity", position: "identity" },
+  smooth: { stat: "smooth", position: "identity" },
+  quantile: { stat: "quantile", position: "identity" },
+  boxplot: { stat: "boxplot", position: "dodge" },
+  density: { stat: "density", position: "identity" },
+  errorbar: { stat: "identity", position: "identity" },
+  linerange: { stat: "identity", position: "identity" },
+  pointrange: { stat: "identity", position: "identity" },
+  crossbar: { stat: "identity", position: "identity" },
+  rect: { stat: "identity", position: "identity" },
+  tile: { stat: "identity", position: "identity" },
+  raster: { stat: "identity", position: "identity" },
+  ribbon: { stat: "identity", position: "identity" },
+  segment: { stat: "identity", position: "identity" },
+  count: { stat: "sum", position: "identity" },
+  violin: { stat: "ydensity", position: "dodge" },
+  function: { stat: "function", position: "identity" },
+  polygon: { stat: "identity", position: "identity" },
+  hex: { stat: "bin_hex", position: "identity" },
+  abline: { stat: "identity", position: "identity" },
+  curve: { stat: "identity", position: "identity" },
+  contour: { stat: "contour", position: "identity" },
+  density_2d: { stat: "density_2d", position: "identity" },
+  density_2d_filled: { stat: "density_2d_filled", position: "identity" },
+  dotplot: { stat: "bindot", position: "identity" },
+  map: { stat: "identity", position: "identity" },
+  sf: { stat: "sf", position: "identity" },
+  sf_text: { stat: "sf_coordinates", position: "identity" },
+  sf_label: { stat: "sf_coordinates", position: "identity" },
+  blank: { stat: "identity", position: "identity" },
+  jitter: { stat: "identity", position: "jitter" },
+  spoke: { stat: "identity", position: "identity" },
+  rug: { stat: "identity", position: "identity" },
+  step: { stat: "identity", position: "identity" },
+  qq: { stat: "qq", position: "identity" },
+  qq_line: { stat: "qq_line", position: "identity" },
+  bin_2d: { stat: "bin_2d", position: "identity" },
+};

package/src/schema-declarations.ts

@@ -0,0 +1,51 @@
+/**
+ * Ordered TypeBox named `$defs` for the ggts PortableSpec graph.
+ *
+ * Key **insertion order** is load-bearing: `Type.Cyclic` / the published
+ * `schema/v0.json` serialize `$defs` in this order. The bag is split into
+ * family partial-record modules (`schema-decls-*.ts`); this aggregator
+ * composes `SpecDeclarations` via spread in the EXACT original key order —
+ * do not reorder spreads or edit field descriptions while relocating.
+ *
+ * Cross-refs use string `Type.Ref("Name")` and resolve only after this object
+ * is passed to `Type.Cyclic` / `Type.Module` in schema.ts.
+ */
+import { DataDecls } from "./schema-decls-data.js";
+import { PaintDecls } from "./schema-decls-paint.js";
+import { ParamsPointPathDecls } from "./schema-decls-params-point-path.js";
+import { ParamsColContourDecls } from "./schema-decls-params-col-contour.js";
+import { ParamsViolinSummaryDecls } from "./schema-decls-params-violin-summary.js";
+import { ParamsErrorbarPositionDecls } from "./schema-decls-params-errorbar-position.js";
+import { ParamsAreaAblineDecls } from "./schema-decls-params-area-abline.js";
+import { ParamsCurveLabelDecls } from "./schema-decls-params-curve-label.js";
+import { LayersPointPathDecls } from "./schema-decls-layers-point-path.js";
+import { LayersColBoxplotDecls } from "./schema-decls-layers-col-boxplot.js";
+import { LayersCountPointrangeDecls } from "./schema-decls-layers-count-pointrange.js";
+import { LayersCrossbarJitterDecls } from "./schema-decls-layers-crossbar-jitter.js";
+import { LayersTextMapDecls } from "./schema-decls-layers-text-map.js";
+import { LayersSfBlankDecls } from "./schema-decls-layers-sf-blank.js";
+import { ScaleDecls } from "./schema-decls-scales.js";
+import { StyleScaleDecls } from "./schema-decls-scales-guides.js";
+import { GuidesThemeDecls } from "./schema-decls-guides-theme.js";
+import { PlotDecls } from "./schema-decls-plot.js";
+
+export const SpecDeclarations = {
+  ...DataDecls,
+  ...PaintDecls,
+  ...ParamsPointPathDecls,
+  ...ParamsColContourDecls,
+  ...ParamsViolinSummaryDecls,
+  ...ParamsErrorbarPositionDecls,
+  ...ParamsAreaAblineDecls,
+  ...ParamsCurveLabelDecls,
+  ...LayersPointPathDecls,
+  ...LayersColBoxplotDecls,
+  ...LayersCountPointrangeDecls,
+  ...LayersCrossbarJitterDecls,
+  ...LayersTextMapDecls,
+  ...LayersSfBlankDecls,
+  ...ScaleDecls,
+  ...StyleScaleDecls,
+  ...GuidesThemeDecls,
+  ...PlotDecls,
+};

package/src/schema-decls-data.ts

@@ -0,0 +1,272 @@
+/**
+ * `$defs` partial — data family (CellValue…Aes).
+ * Composed by schema-declarations.ts via spread; key insertion order is load-bearing.
+ */
+
+import Type from "typebox";
+
+export const DataDecls = {
+  CellValue: Type.Union([Type.String(), Type.Number(), Type.Boolean(), Type.Null()], {
+    description:
+      'A single data cell: string, number, boolean, or null. Dates travel as ISO 8601 strings (e.g. "2026-07-10"); non-finite numbers travel as null.',
+  }),
+
+  DataValues: Type.Object(
+    {
+      values: Type.Array(
+        Type.Object(
+          {},
+          {
+            additionalProperties: Type.Ref("CellValue"),
+            description: "One data row: an object mapping field names to cell values.",
+          },
+        ),
+        {
+          description: "Row-oriented inline data: an array of row objects sharing field names.",
+        },
+      ),
+    },
+    {
+      additionalProperties: false,
+      description: 'Inline row-oriented data. Example: {"values": [{"x": 1, "y": 2}]}.',
+    },
+  ),
+
+  DataColumns: Type.Object(
+    {
+      columns: Type.Record(Type.String(), Type.Array(Type.Ref("CellValue")), {
+        description:
+          "Column-oriented inline data: an object mapping each field name to an array of cell values. All arrays must have the same length.",
+      }),
+    },
+    {
+      additionalProperties: false,
+      description: 'Inline column-oriented data. Example: {"columns": {"x": [1, 2], "y": [3, 4]}}.',
+    },
+  ),
+
+  DataName: Type.Object(
+    {
+      name: Type.String({
+        description:
+          "Name of a dataset provided out-of-band: either a key of the spec's top-level `datasets`, or a dataset passed by the host at render time.",
+      }),
+    },
+    {
+      additionalProperties: false,
+      description: 'A reference to a named dataset. Example: {"name": "cars"}.',
+    },
+  ),
+
+  DataRef: Type.Union([Type.Ref("DataValues"), Type.Ref("DataColumns"), Type.Ref("DataName")], {
+    description:
+      "Where a plot's data comes from: inline rows ({values}), inline columns ({columns}), or a named dataset ({name}). Exactly one form.",
+  }),
+
+  InlineData: Type.Union([Type.Ref("DataValues"), Type.Ref("DataColumns")], {
+    description: "Inline data only ({values} or {columns}); used for entries of `datasets`.",
+  }),
+
+  FieldRef: Type.Object(
+    {
+      field: Type.String({
+        description: "Name of the data column this channel reads from.",
+      }),
+    },
+    {
+      additionalProperties: false,
+      description:
+        'Map this channel to a data field (column). Example: {"field": "displ"}. This is the canonical form — bare strings are NOT valid channel values.',
+    },
+  ),
+
+  ValueRef: Type.Object(
+    {
+      value: Type.Union([Type.String(), Type.Number(), Type.Boolean()], {
+        description: "The constant value applied to every mark.",
+      }),
+      scale: Type.Optional(
+        Type.Boolean({
+          description:
+            "If true, the constant is passed THROUGH the channel's scale (like a data value). Default false: the constant is used literally (e.g. a CSS color).",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        'Map this channel to a constant. Example: {"value": "steelblue"} sets a literal color; {"value": "treatment", "scale": true} routes the constant through the scale.',
+    },
+  ),
+
+  StatRef: Type.Object(
+    {
+      stat: Type.String({
+        description:
+          'Name of a stat-generated column computed after the layer\'s stat runs (e.g. "count" for the count stat). after_stat.',
+      }),
+    },
+    {
+      additionalProperties: false,
+      description:
+        'Map this channel to a column generated by the layer\'s stat (after-stat form). Example: {"stat": "count"}.',
+    },
+  ),
+
+  ChannelValue: Type.Union(
+    [Type.Ref("FieldRef"), Type.Ref("ValueRef"), Type.Ref("StatRef"), Type.Null()],
+    {
+      description:
+        "How one aesthetic channel gets its value: a data field ({field}), a constant ({value, scale?}), a stat output ({stat}), or null to UNSET a channel inherited from the plot-level mapping. Bare strings are not valid.",
+    },
+  ),
+
+  Aes: Type.Object(
+    {
+      x: Type.Optional(Type.Ref("ChannelValue", { description: "Horizontal position channel." })),
+      y: Type.Optional(Type.Ref("ChannelValue", { description: "Vertical position channel." })),
+      color: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Stroke/point color channel. Discrete fields get a categorical palette; quantitative fields get a sequential ramp.",
+        }),
+      ),
+      fill: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Fill color channel (areas, bars, filled shapes). Discrete fields get a categorical palette; quantitative fields get a sequential ramp.",
+        }),
+      ),
+      size: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Mark size channel (AREA-scaled — sqrt scale; use `linewidth` for stroke width, which scales linearly).",
+        }),
+      ),
+      linewidth: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Stroke width channel (LENGTH-scaled — linear; distinct from `size`, which scales by area).",
+        }),
+      ),
+      alpha: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description: "Opacity channel, 0 (transparent) to 1 (opaque).",
+        }),
+      ),
+      shape: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description: "Finite point-symbol channel. Continuous values require a binned scale.",
+        }),
+      ),
+      linetype: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description: "Finite stroke-pattern channel. Continuous values require a binned scale.",
+        }),
+      ),
+      group: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            'Explicit grouping channel. Overrides the default grouping (the interaction of all discrete mapped aesthetics). A constant (e.g. {"value": 1}) forces a single group.',
+        }),
+      ),
+      label: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Text label channel (used by the text geom; never participates in grouping).",
+        }),
+      ),
+      weight: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Statistical weight channel. The count, bin, and density stats sum weights instead of counting rows. Never participates in grouping.",
+        }),
+      ),
+      sample: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Sample distribution channel for Q–Q plots. The qq / qq_line stats read this column; x/y become theoretical and sample quantiles after the stat. Never participates in grouping.",
+        }),
+      ),
+      ymin: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Lower y bound (errorbar identity, rect edges, ribbon x-orientation). Quantitative values only.",
+        }),
+      ),
+      ymax: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Upper y bound (errorbar identity, rect edges, ribbon x-orientation). Quantitative values only.",
+        }),
+      ),
+      xmin: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Left edge / lower x bound (geom rect; ribbon y-orientation). Quantitative values only.",
+        }),
+      ),
+      xmax: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Right edge / upper x bound (geom rect; ribbon y-orientation). Quantitative values only.",
+        }),
+      ),
+      xend: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Segment end x (geom segment). Trains the x scale together with aes.x; may be discrete or continuous.",
+        }),
+      ),
+      yend: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Segment end y (geom segment). Trains the y scale together with aes.y; may be discrete or continuous.",
+        }),
+      ),
+      width: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Cell width for geom tile (data units after position transform; not a trained position scale). Prefer params.width for a constant.",
+        }),
+      ),
+      height: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Cell height for geom tile (data units after position transform; not a trained position scale). Prefer params.height for a constant.",
+        }),
+      ),
+      z: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Surface height for geom contour / stat contour (quantitative grid values over continuous x×y;).",
+        }),
+      ),
+      map_id: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Region join key for geom_map (value-table column matched to the map data id column;).",
+        }),
+      ),
+      angle: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Spoke direction in radians (geom spoke; 0 = +x, π/2 = +y). Quantitative only. May also be set as params.angle.",
+        }),
+      ),
+      radius: Type.Optional(
+        Type.Ref("ChannelValue", {
+          description:
+            "Spoke length in data units (geom spoke). Quantitative only. May also be set as params.radius.",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Aesthetic mapping: which channels read which data fields/constants. Plot-level aes is inherited by every layer; a layer's aes overrides per channel, and null unsets an inherited channel.",
+    },
+  ),
+
+  // --- within-mark paint (#591) ----------------------------------------------
+};