@ggts-sh/spec 0.43.0

package/src/schema-decls-params-col-contour.ts

@@ -0,0 +1,333 @@
+/**
+ * `$defs` partial — column/stat geom params (ColParams…ContourParams).
+ * Composed by schema-declarations.ts via spread; key insertion order is load-bearing.
+ */
+
+import Type from "typebox";
+import { POINT_SHAPE_NAME_SCHEMAS } from "./schema-name-schemas.js";
+
+export const ParamsColContourDecls = {
+  ColParams: Type.Object(
+    {
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Bar opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      width: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          maximum: 1,
+          description:
+            "Bar width as a fraction of the band step. Must be greater than 0 and at most 1. Default 0.9.",
+        }),
+      ),
+      fillPaint: Type.Optional(
+        Type.Ref("GradientPaint", {
+          description:
+            "Within-mark gradient fill paint (not a data scale). Requires a solid fallback.",
+        }),
+      ),
+      glow: Type.Optional(
+        Type.Ref("GlowSpec", {
+          description: "Bounded within-mark glow treatment (not theme decoration).",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description: "Styling parameters for the col geom.",
+    },
+  ),
+
+  BarParams: Type.Object(
+    {
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Bar opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      width: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          maximum: 1,
+          description:
+            "Bar width as a fraction of the band step (count-stat bars only; binned bars span their bin). Must be greater than 0 and at most 1. Default 0.9.",
+        }),
+      ),
+      bins: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          description:
+            "STAT BIN ONLY: number of bins (an integer of at least 1). Default 30 — an advisory reminds you to pick a real value. Overridden by binwidth.",
+        }),
+      ),
+      binwidth: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description:
+            "STAT BIN ONLY: bin width in data units (must be greater than 0). Takes precedence over bins. Usually the better knob: pick a width meaningful for the data.",
+        }),
+      ),
+      boundary: Type.Optional(
+        Type.Number({
+          description:
+            "STAT BIN ONLY: align a bin EDGE with this x value (e.g. 0 puts bin edges at multiples of the width). Mutually exclusive with center.",
+        }),
+      ),
+      center: Type.Optional(
+        Type.Number({
+          description:
+            "STAT BIN ONLY: align a bin CENTER with this x value. Mutually exclusive with boundary.",
+        }),
+      ),
+      closed: Type.Optional(
+        Type.Union([Type.Literal("right"), Type.Literal("left")], {
+          description:
+            'STAT BIN ONLY: which edge of each bin is inclusive: "right" (default, matches) or "left".',
+        }),
+      ),
+      fillPaint: Type.Optional(
+        Type.Ref("GradientPaint", {
+          description:
+            "Within-mark gradient fill paint (not a data scale). Requires a solid fallback.",
+        }),
+      ),
+      glow: Type.Optional(
+        Type.Ref("GlowSpec", {
+          description: "Bounded within-mark glow treatment (not theme decoration).",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Parameters for the bar and histogram geoms: styling (alpha, width) plus stat-bin binning controls (bins, binwidth, boundary, center, closed).",
+    },
+  ),
+
+  SmoothParams: Type.Object(
+    {
+      method: Type.Optional(
+        Type.Union([Type.Literal("lm"), Type.Literal("loess")], {
+          description:
+            'Smoothing method: "lm" (least-squares line) or "loess" (local polynomial regression). Omit to infer: loess for fewer than 1000 rows, lm above (an advisory reports the choice).',
+        }),
+      ),
+      se: Type.Optional(
+        Type.Boolean({
+          description: "Draw the confidence-interval ribbon around the fit. Default true.",
+        }),
+      ),
+      level: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          exclusiveMaximum: 1,
+          description: "Confidence level of the ribbon, strictly between 0 and 1. Default 0.95.",
+        }),
+      ),
+      span: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          maximum: 1,
+          description:
+            "LOESS ONLY: fraction of points in each local neighborhood, greater than 0 and at most 1. Default 0.75. Smaller = wigglier.",
+        }),
+      ),
+      degree: Type.Optional(
+        Type.Union([Type.Literal(1), Type.Literal(2)], {
+          description:
+            "LOESS ONLY: degree of the local polynomial, 1 or 2. Default 2 (the R default).",
+        }),
+      ),
+      n: Type.Optional(
+        Type.Integer({
+          minimum: 2,
+          maximum: 5000,
+          description:
+            "Number of evaluation points along x (an integer between 2 and 5000). Default 80.",
+        }),
+      ),
+      linewidth: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Stroke width of the fitted line in px. Must be greater than 0. Default 1.",
+        }),
+      ),
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Line opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      strokePaint: Type.Optional(
+        Type.Ref("GradientPaint", {
+          description: "Within-mark gradient stroke paint for the fitted line (not a data scale).",
+        }),
+      ),
+      glow: Type.Optional(
+        Type.Ref("GlowSpec", {
+          description: "Bounded within-mark glow treatment (not theme decoration).",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description: "Parameters for the smooth geom (fitted trend line + optional se ribbon).",
+    },
+  ),
+
+  QuantileParams: Type.Object(
+    {
+      quantiles: Type.Optional(
+        Type.Array(
+          Type.Number({
+            exclusiveMinimum: 0,
+            exclusiveMaximum: 1,
+            description: "One conditional quantile τ strictly between 0 and 1.",
+          }),
+          {
+            minItems: 1,
+            description:
+              "Conditional quantiles of y to fit and draw. Each entry must be in (0, 1). Default [0.25, 0.5, 0.75].",
+          },
+        ),
+      ),
+      n: Type.Optional(
+        Type.Integer({
+          minimum: 2,
+          maximum: 5000,
+          description:
+            "Number of evaluation points along x (integer 2–5000). Default 80. Linear fits need only endpoints; denser grids help nonlinear coords.",
+        }),
+      ),
+      linewidth: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Stroke width of quantile lines in px. Must be greater than 0. Default 1.",
+        }),
+      ),
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Line opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      strokePaint: Type.Optional(
+        Type.Ref("GradientPaint", {
+          description: "Within-mark gradient stroke paint for quantile lines (not a data scale).",
+        }),
+      ),
+      glow: Type.Optional(
+        Type.Ref("GlowSpec", {
+          description: "Bounded within-mark glow treatment (not theme decoration).",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Parameters for the quantile geom (linear y~x quantile regression lines;). method rqss is intentionally omitted in v1.",
+    },
+  ),
+  QqParams: Type.Object(
+    {
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Point opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      size: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Point size in px. Must be greater than 0.",
+        }),
+      ),
+      shape: Type.Optional(
+        Type.Union(POINT_SHAPE_NAME_SCHEMAS, {
+          description:
+            'Point shape. One of "circle", "triangle", "square", "diamond", "plus", "cross", "circle-open". Default "circle".',
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Styling for geom_qq (Q–Q scatter). Requires aes.sample; x/y become theoretical and sample quantiles.",
+    },
+  ),
+  QqLineParams: Type.Object(
+    {
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Line opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      linewidth: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Stroke width in px. Must be greater than 0. Default 1.",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Styling for geom_qq_line (reference line through sample/theoretical quartile match).",
+    },
+  ),
+
+  ContourParams: Type.Object(
+    {
+      bins: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          description:
+            "Number of evenly spaced contour levels from min(z) to max(z) inclusive (integer ≥ 1). Default 10. Overridden by breaks or binwidth.",
+        }),
+      ),
+      binwidth: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description:
+            "Contour level step in z units (must be greater than 0). Takes precedence over bins; overridden by breaks.",
+        }),
+      ),
+      breaks: Type.Optional(
+        Type.Array(Type.Number(), {
+          minItems: 1,
+          description:
+            "Explicit contour levels (finite numbers). Overrides bins and binwidth when non-empty.",
+        }),
+      ),
+      linewidth: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Stroke width of contour lines in px. Must be greater than 0. Default 1.",
+        }),
+      ),
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Line opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Parameters for geom_contour isolines. v1: regular grid only; contour_filled deferred.",
+    },
+  ),
+};

package/src/schema-decls-params-curve-label.ts

@@ -0,0 +1,343 @@
+/**
+ * `$defs` partial — curve/map/text geom params (CurveParams…IdentityOrUniqueStat).
+ * Composed by schema-declarations.ts via spread; key insertion order is load-bearing.
+ */
+
+import Type from "typebox";
+
+export const ParamsCurveLabelDecls = {
+  CurveParams: Type.Object(
+    {
+      curvature: Type.Optional(
+        Type.Number({
+          description:
+            "Amount of bend away from the straight chord. 0 is a straight line; default 0.5. Positive bows to the right of the start→end direction when angle is 90.",
+        }),
+      ),
+      angle: Type.Optional(
+        Type.Number({
+          description:
+            "Control-point direction relative to the chord, in degrees. default 90 (perpendicular).",
+        }),
+      ),
+      ncp: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          maximum: 50,
+          description:
+            "Smoothness density knob. Maps to tessellation sample count = max(8, ncp×8); not multi-control xspline. Default 5.",
+        }),
+      ),
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Curve opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      linewidth: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Stroke width in px. Must be greater than 0. Default 1.",
+        }),
+      ),
+      lineend: Type.Optional(
+        Type.Union([Type.Literal("butt"), Type.Literal("round"), Type.Literal("square")], {
+          description: 'SVG stroke-linecap for curve ends. Default "butt".',
+        }),
+      ),
+      strokePaint: Type.Optional(
+        Type.Ref("GradientPaint", {
+          description:
+            "Within-mark gradient stroke paint (not a data scale). Requires a solid fallback.",
+        }),
+      ),
+      glow: Type.Optional(
+        Type.Ref("GlowSpec", {
+          description: "Bounded within-mark glow treatment (not theme decoration).",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Parameters for geom curve: curvature/angle/ncp plus segment-like stroke styling.",
+    },
+  ),
+
+  PolygonParams: Type.Object(
+    {
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description:
+            "Polygon fill/stroke opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      linewidth: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description:
+            "Outline stroke width in px. Must be greater than 0. Default matches line (1.5).",
+        }),
+      ),
+      fillPaint: Type.Optional(
+        Type.Ref("GradientPaint", {
+          description:
+            "Within-mark gradient fill paint (not a data scale). Requires a solid fallback.",
+        }),
+      ),
+      strokePaint: Type.Optional(
+        Type.Ref("GradientPaint", {
+          description:
+            "Within-mark gradient stroke paint (not a data scale). Requires a solid fallback.",
+        }),
+      ),
+      glow: Type.Optional(
+        Type.Ref("GlowSpec", {
+          description: "Bounded within-mark glow treatment (not theme decoration).",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Styling parameters for the polygon geom (closed filled path from (x,y) vertices).",
+    },
+  ),
+
+  MapParams: Type.Object(
+    {
+      map: Type.Ref("DataRef", {
+        description:
+          "Fortified map coordinates ({ values }, { columns }, or { name } against spec.datasets). Must include long+lat or x+y, plus a region id column.",
+      }),
+      mapId: Type.Optional(
+        Type.String({
+          minLength: 1,
+          description:
+            'Join column name in the map data (matched to aes.map_id). Default: "region", then "id".',
+        }),
+      ),
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Region fill opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      linewidth: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Region outline stroke width in px. Must be greater than 0. Default 1.5.",
+        }),
+      ),
+      fillPaint: Type.Optional(
+        Type.Ref("GradientPaint", {
+          description: "Within-mark gradient fill paint (not a data scale).",
+        }),
+      ),
+      strokePaint: Type.Optional(
+        Type.Ref("GradientPaint", {
+          description: "Within-mark gradient stroke paint (not a data scale).",
+        }),
+      ),
+      glow: Type.Optional(
+        Type.Ref("GlowSpec", {
+          description: "Bounded within-mark glow treatment (not theme decoration).",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Parameters for geom_map: fortified map DataRef plus optional join column and polygon styling.",
+    },
+  ),
+
+  SfParams: Type.Object(
+    {
+      geometry: Type.Optional(
+        Type.String({
+          minLength: 1,
+          description:
+            'Name of the data column holding GeoJSON Geometry JSON strings. Default "geometry". Already-projected coordinates only.',
+        }),
+      ),
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Mark opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      linewidth: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Stroke width in px for lines/polygon outlines. Must be greater than 0.",
+        }),
+      ),
+      size: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Point radius in px when geometries are Point/MultiPoint.",
+        }),
+      ),
+      fillPaint: Type.Optional(
+        Type.Ref("GradientPaint", {
+          description: "Within-mark gradient fill paint (polygon family; not a data scale).",
+        }),
+      ),
+      strokePaint: Type.Optional(
+        Type.Ref("GradientPaint", {
+          description: "Within-mark gradient stroke paint (not a data scale).",
+        }),
+      ),
+      glow: Type.Optional(
+        Type.Ref("GlowSpec", {
+          description: "Bounded within-mark glow treatment (not theme decoration).",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Parameters for geom_sf: portable GeoJSON Geometry column plus styling. Interior rings are even-odd holes; GeometryCollection expands. Use coord_sf for fixed-aspect maps (CRS reproject deferred).",
+    },
+  ),
+
+  TextParams: Type.Object(
+    {
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Text opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      size: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Font size in px. Must be greater than 0. Default 11.",
+        }),
+      ),
+      anchor: Type.Optional(
+        Type.Union([Type.Literal("start"), Type.Literal("middle"), Type.Literal("end")], {
+          description:
+            'Horizontal text anchor relative to the (x, y) position: "start", "middle" (default), or "end".',
+        }),
+      ),
+      dx: Type.Optional(
+        Type.Number({
+          description: "Horizontal offset in px applied after positioning. Default 0.",
+        }),
+      ),
+      dy: Type.Optional(
+        Type.Number({
+          description:
+            "Vertical offset in px applied after positioning (positive = down). Default 0.",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Styling parameters for the text geom (no collision detection: labels draw exactly where placed).",
+    },
+  ),
+
+  LabelParams: Type.Object(
+    {
+      alpha: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          maximum: 1,
+          description: "Label opacity. Must be between 0 and 1 (inclusive). Default 1.",
+        }),
+      ),
+      size: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Font size in px. Must be greater than 0. Default 11.",
+        }),
+      ),
+      anchor: Type.Optional(
+        Type.Union([Type.Literal("start"), Type.Literal("middle"), Type.Literal("end")], {
+          description:
+            'Horizontal text anchor relative to the (x, y) position: "start", "middle" (default), or "end".',
+        }),
+      ),
+      dx: Type.Optional(
+        Type.Number({
+          description: "Horizontal offset in px applied after positioning. Default 0.",
+        }),
+      ),
+      dy: Type.Optional(
+        Type.Number({
+          description:
+            "Vertical offset in px applied after positioning (positive = down). Default 0.",
+        }),
+      ),
+      padding: Type.Optional(
+        Type.Number({
+          exclusiveMinimum: 0,
+          description: "Uniform box padding around the text in px. Default 3.",
+        }),
+      ),
+      radius: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          description: "Corner radius of the background box in px. Default 3.",
+        }),
+      ),
+      linewidth: Type.Optional(
+        Type.Number({
+          minimum: 0,
+          description: "Box outline stroke width in px. Default 0.5.",
+        }),
+      ),
+    },
+    {
+      additionalProperties: false,
+      description:
+        "Styling parameters for the label geom (text with background box; no collision detection).",
+    },
+  ),
+
+  // --- rendering backend -------------------------------------------------------
+
+  RenderBackend: Type.Union([Type.Literal("svg"), Type.Literal("canvas"), Type.Literal("auto")], {
+    description:
+      'Rendering backend for this layer: "svg" (DOM marks — accessible, copyable), "canvas" (fast raster for high mark counts), or "auto" (default — canvas above the mark-count threshold of 2000, with an advisory). Text layers always render as SVG. renderToSVGString ignores this and renders everything as SVG.',
+  }),
+
+  // --- positions ------------------------------------------------------------
+
+  StackablePosition: Type.Union(
+    [Type.Literal("stack"), Type.Literal("fill"), Type.Literal("dodge"), Type.Literal("identity")],
+    {
+      description:
+        'Position adjustment: "stack" piles grouped values (positive up, negative down), "fill" stacks to proportions of 1, "dodge" places groups side by side, "identity" leaves positions unchanged.',
+    },
+  ),
+
+  /** Identity-capable layers may also use unique (first-wins aesthetic dedupe). */
+  IdentityOrUniqueStat: Type.Union(
+    [
+      Type.Literal("identity", {
+        description: "Draw each data row as-is (no aggregation or row filter).",
+      }),
+      Type.Literal("unique", {
+        description:
+          "Drop duplicate rows on the combination of mapped aesthetic fields before drawing; first occurrence wins. Panel-local.",
+      }),
+    ],
+    {
+      description:
+        'Layer stat: "identity" (default) or "unique" (dedupe mapped aesthetics, first wins).',
+    },
+  ),
+
+  // --- layers (discriminated by geom) ----------------------------------------
+};