@ggts-sh/spec 0.43.0

package/src/capabilities-data.ts

@@ -0,0 +1,336 @@
+/**
+ * Checked public capability ledger.
+ *
+ * `scaleTypes` are the CANONICAL post-normalize scale families a runtime
+ * implements. `authoredAliases` are accepted authoring spellings that
+ * `normalize()` rewrites into a canonical family (e.g. `type: "log"` becomes
+ * `{ type: "linear", transform: "log10" }`) — they never re-appear in
+ * `scaleTypes`. `transforms` are the pre-stat position transforms the family
+ * supports. `helpers` are the exported camelCase + ggplot2 snake_case helpers.
+ *
+ * `packages/spec/tests/capabilities.test.ts` cross-validates this ledger:
+ * every claimed helper is a real package-root export with binding-identical
+ * aliases, normalizes to its declared family, and surfaces in generated docs.
+ */
+export const SCALE_CAPABILITIES = [
+  {
+    family: "position-continuous",
+    aesthetics: ["x", "y"],
+    scaleTypes: ["linear"],
+    transforms: ["identity", "log10", "sqrt"],
+    authoredAliases: ["log"],
+    runtime: "implemented",
+    helpers: [
+      "scaleXContinuous",
+      "scaleYContinuous",
+      "scaleXLog10",
+      "scaleYLog10",
+      "scaleXSqrt",
+      "scaleYSqrt",
+      "scaleXReverse",
+      "scaleYReverse",
+      "scale_x_continuous",
+      "scale_y_continuous",
+      "scale_x_log10",
+      "scale_y_log10",
+      "scale_x_sqrt",
+      "scale_y_sqrt",
+      "scale_x_reverse",
+      "scale_y_reverse",
+    ],
+  },
+  {
+    family: "position-binned",
+    aesthetics: ["x", "y"],
+    scaleTypes: ["binned"],
+    transforms: ["identity", "log10", "sqrt"],
+    authoredAliases: [] as const,
+    runtime: "implemented",
+    helpers: ["scaleXBinned", "scaleYBinned", "scale_x_binned", "scale_y_binned"],
+  },
+  {
+    family: "position-temporal",
+    aesthetics: ["x", "y"],
+    scaleTypes: ["time"],
+    transforms: ["identity"],
+    authoredAliases: [] as const,
+    runtime: "implemented",
+    helpers: [
+      "scaleXDate",
+      "scaleXDatetime",
+      "scaleXTime",
+      "scaleYDate",
+      "scaleYDatetime",
+      "scaleYTime",
+      "scaleXMonthDay",
+      "scaleYMonthDay",
+      "scale_x_date",
+      "scale_x_datetime",
+      "scale_x_time",
+      "scale_y_date",
+      "scale_y_datetime",
+      "scale_y_time",
+      "scale_x_month_day",
+      "scale_y_month_day",
+    ],
+  },
+  {
+    family: "position-discrete",
+    aesthetics: ["x", "y"],
+    scaleTypes: ["band"],
+    transforms: [] as const,
+    authoredAliases: [] as const,
+    runtime: "implemented",
+    helpers: ["scaleXDiscrete", "scaleYDiscrete", "scale_x_discrete", "scale_y_discrete"],
+  },
+  {
+    family: "color-fill",
+    aesthetics: ["color", "fill"],
+    scaleTypes: ["ordinal", "sequential", "binned", "manual", "identity"],
+    transforms: ["identity", "log10", "sqrt"],
+    authoredAliases: [] as const,
+    runtime: "implemented",
+    helpers: [
+      "scaleColorContinuous",
+      "scaleColorDiscrete",
+      "scaleColorBinned",
+      "scaleColorLog10",
+      "scaleColorSqrt",
+      "scaleColorDate",
+      "scaleColorDatetime",
+      "scaleColorManual",
+      "scaleColorIdentity",
+      "scaleColorSteps",
+      "scaleColorSteps2",
+      "scaleColorStepsn",
+      "scaleColorGradient",
+      "scaleColorGradient2",
+      "scaleColorGradientn",
+      "scaleColorHue",
+      "scaleColorGrey",
+      "scaleColorOrdinal",
+      "scaleColorBrewer",
+      "scaleColorDistiller",
+      "scaleColorFermenter",
+      "scaleColourContinuous",
+      "scaleColourDiscrete",
+      "scaleColourBinned",
+      "scaleColourLog10",
+      "scaleColourSqrt",
+      "scaleColourDate",
+      "scaleColourDatetime",
+      "scaleColourManual",
+      "scaleColourIdentity",
+      "scaleColourSteps",
+      "scaleColourSteps2",
+      "scaleColourStepsn",
+      "scaleColourGradient",
+      "scaleColourGradient2",
+      "scaleColourGradientn",
+      "scaleColourHue",
+      "scaleColourGrey",
+      "scaleColourOrdinal",
+      "scaleColourBrewer",
+      "scaleColourDistiller",
+      "scaleColourFermenter",
+      "scaleFillContinuous",
+      "scaleFillDiscrete",
+      "scaleFillBinned",
+      "scaleFillLog10",
+      "scaleFillSqrt",
+      "scaleFillDate",
+      "scaleFillDatetime",
+      "scaleFillManual",
+      "scaleFillIdentity",
+      "scaleFillSteps",
+      "scaleFillSteps2",
+      "scaleFillStepsn",
+      "scaleFillGradient",
+      "scaleFillGradient2",
+      "scaleFillGradientn",
+      "scaleFillHue",
+      "scaleFillGrey",
+      "scaleFillOrdinal",
+      "scaleFillBrewer",
+      "scaleFillDistiller",
+      "scaleFillFermenter",
+      "scale_color_continuous",
+      "scale_color_discrete",
+      "scale_color_binned",
+      "scale_color_log10",
+      "scale_color_sqrt",
+      "scale_color_date",
+      "scale_color_datetime",
+      "scale_color_manual",
+      "scale_color_identity",
+      "scale_color_steps",
+      "scale_color_steps2",
+      "scale_color_stepsn",
+      "scale_color_gradient",
+      "scale_color_gradient2",
+      "scale_color_gradientn",
+      "scale_color_hue",
+      "scale_color_grey",
+      "scale_color_gray",
+      "scale_color_ordinal",
+      "scale_color_brewer",
+      "scale_color_distiller",
+      "scale_color_fermenter",
+      "scale_colour_continuous",
+      "scale_colour_discrete",
+      "scale_colour_binned",
+      "scale_colour_log10",
+      "scale_colour_sqrt",
+      "scale_colour_date",
+      "scale_colour_datetime",
+      "scale_colour_manual",
+      "scale_colour_identity",
+      "scale_colour_steps",
+      "scale_colour_steps2",
+      "scale_colour_stepsn",
+      "scale_colour_gradient",
+      "scale_colour_gradient2",
+      "scale_colour_gradientn",
+      "scale_colour_hue",
+      "scale_colour_grey",
+      "scale_colour_gray",
+      "scale_colour_ordinal",
+      "scale_colour_brewer",
+      "scale_colour_distiller",
+      "scale_colour_fermenter",
+      "scale_fill_continuous",
+      "scale_fill_discrete",
+      "scale_fill_binned",
+      "scale_fill_log10",
+      "scale_fill_sqrt",
+      "scale_fill_date",
+      "scale_fill_datetime",
+      "scale_fill_manual",
+      "scale_fill_identity",
+      "scale_fill_steps",
+      "scale_fill_steps2",
+      "scale_fill_stepsn",
+      "scale_fill_gradient",
+      "scale_fill_gradient2",
+      "scale_fill_gradientn",
+      "scale_fill_hue",
+      "scale_fill_grey",
+      "scale_fill_gray",
+      "scale_fill_ordinal",
+      "scale_fill_brewer",
+      "scale_fill_distiller",
+      "scale_fill_fermenter",
+      "scaleColorViridisC",
+      "scaleColorViridisD",
+      "scaleColorViridisB",
+      "scaleColourViridisC",
+      "scaleColourViridisD",
+      "scaleColourViridisB",
+      "scaleFillViridisC",
+      "scaleFillViridisD",
+      "scaleFillViridisB",
+      "scale_color_viridis_c",
+      "scale_color_viridis_d",
+      "scale_color_viridis_b",
+      "scale_colour_viridis_c",
+      "scale_colour_viridis_d",
+      "scale_colour_viridis_b",
+      "scale_fill_viridis_c",
+      "scale_fill_viridis_d",
+      "scale_fill_viridis_b",
+    ],
+  },
+  {
+    family: "numeric-style",
+    aesthetics: ["size", "linewidth", "alpha"],
+    scaleTypes: ["sequential", "ordinal", "binned", "manual", "identity"],
+    transforms: ["identity"],
+    authoredAliases: [] as const,
+    runtime: "implemented",
+    helpers: [
+      "scaleSizeContinuous",
+      "scaleSizeDiscrete",
+      "scaleSizeBinned",
+      "scaleSizeDate",
+      "scaleSizeDatetime",
+      "scaleSizeManual",
+      "scaleSizeIdentity",
+      "scaleSizeArea",
+      "scaleSizeBinnedArea",
+      "scaleRadius",
+      "scaleLinewidthContinuous",
+      "scaleLinewidthDiscrete",
+      "scaleLinewidthBinned",
+      "scaleLinewidthDate",
+      "scaleLinewidthDatetime",
+      "scaleLinewidthManual",
+      "scaleLinewidthIdentity",
+      "scaleAlphaContinuous",
+      "scaleAlphaDiscrete",
+      "scaleAlphaBinned",
+      "scaleAlphaDate",
+      "scaleAlphaDatetime",
+      "scaleAlphaManual",
+      "scaleAlphaIdentity",
+      "scale_size_continuous",
+      "scale_size_discrete",
+      "scale_size_binned",
+      "scale_size_date",
+      "scale_size_datetime",
+      "scale_size_manual",
+      "scale_size_identity",
+      "scale_size",
+      "scale_size_area",
+      "scale_size_binned_area",
+      "scale_size_ordinal",
+      "scale_radius",
+      "scale_linewidth_continuous",
+      "scale_linewidth_discrete",
+      "scale_linewidth_binned",
+      "scale_linewidth_date",
+      "scale_linewidth_datetime",
+      "scale_linewidth_manual",
+      "scale_linewidth_identity",
+      "scale_linewidth",
+      "scale_linewidth_ordinal",
+      "scale_alpha_continuous",
+      "scale_alpha_discrete",
+      "scale_alpha_binned",
+      "scale_alpha_date",
+      "scale_alpha_datetime",
+      "scale_alpha_manual",
+      "scale_alpha_identity",
+      "scale_alpha",
+      "scale_alpha_ordinal",
+    ],
+  },
+  {
+    family: "finite-style",
+    aesthetics: ["shape", "linetype"],
+    scaleTypes: ["ordinal", "binned", "manual", "identity"],
+    transforms: [] as const,
+    authoredAliases: [] as const,
+    runtime: "implemented",
+    helpers: [
+      "scaleShapeDiscrete",
+      "scaleShapeBinned",
+      "scaleShapeManual",
+      "scaleShapeIdentity",
+      "scaleLinetypeDiscrete",
+      "scaleLinetypeBinned",
+      "scaleLinetypeManual",
+      "scaleLinetypeIdentity",
+      "scale_shape",
+      "scale_shape_discrete",
+      "scale_shape_ordinal",
+      "scale_shape_binned",
+      "scale_shape_manual",
+      "scale_shape_identity",
+      "scale_linetype",
+      "scale_linetype_discrete",
+      "scale_linetype_binned",
+      "scale_linetype_manual",
+      "scale_linetype_identity",
+    ],
+  },
+] as const;

package/src/capabilities-helpers.ts

@@ -0,0 +1,54 @@
+/**
+ * Derived helper views over the scale-capability ledger.
+ *
+ * Imports the raw `SCALE_CAPABILITIES` data from `capabilities-data.ts`
+ * (a leaf module) so this file and the `capabilities.ts` facade never form
+ * a runtime cycle — the `STYLE_AESTHETIC_GEOMS` reference below is a
+ * type-only import, erased at runtime.
+ */
+import type { STYLE_AESTHETIC_GEOMS } from "./capabilities.js";
+import { SCALE_CAPABILITIES } from "./capabilities-data.js";
+
+export type ScaleCapability = (typeof SCALE_CAPABILITIES)[number];
+
+/**
+ * CamelCase non-Colour helpers declared on `SCALE_CAPABILITIES`.
+ * Shared source for builder generation, Scale* shell completeness, and tests
+ * so helper-name sets are not re-derived by hand in each consumer (#1081 PR B).
+ */
+export function scaleCapabilityCamelHelpers(): readonly string[] {
+  const out = new Set<string>();
+  for (const cap of SCALE_CAPABILITIES) {
+    for (const h of cap.helpers) {
+      if (h.includes("_")) continue;
+      if (h.includes("Colour")) continue;
+      out.add(h);
+    }
+  }
+  return [...out].toSorted();
+}
+
+/**
+ * ggplot2-style ordinal camelCase aliases for style channels
+ * (binding-identical to the corresponding `*Discrete` helpers).
+ *
+ * Component shells re-export Ordinal names as aliases of Discrete shells
+ * (#830/#832) — they are NOT separate SHELL_MANIFEST entries, so they stay
+ * off the main ledger helper arrays. The builder mixin and package root still
+ * expose them; this constant is the single source for that extra set.
+ */
+export const STYLE_ORDINAL_SCALE_HELPERS = [
+  "scaleSizeOrdinal",
+  "scaleAlphaOrdinal",
+  "scaleLinewidthOrdinal",
+  "scaleShapeOrdinal",
+] as const;
+
+/** Helpers the GGBuilder scale mixin must wrap (ledger camel + style ordinals). */
+export function builderScaleHelperNames(): readonly string[] {
+  return [
+    ...new Set([...scaleCapabilityCamelHelpers(), ...STYLE_ORDINAL_SCALE_HELPERS]),
+  ].toSorted();
+}
+
+export type StyleAesthetic = keyof typeof STYLE_AESTHETIC_GEOMS;

package/src/capabilities.ts

@@ -0,0 +1,159 @@
+/**
+ * Checked geom-consumption facade + re-export surface for the capability
+ * ledger.
+ *
+ * `SCALE_CAPABILITIES` (raw ledger data) lives in `capabilities-data.ts`;
+ * the derived helper views live in `capabilities-helpers.ts`. This module
+ * owns the `STYLE_AESTHETIC_GEOMS` table and re-exports every previously
+ * exported symbol so existing `'./capabilities.js'` import sites are
+ * unchanged.
+ */
+export { SCALE_CAPABILITIES } from "./capabilities-data.js";
+export {
+  builderScaleHelperNames,
+  scaleCapabilityCamelHelpers,
+  STYLE_ORDINAL_SCALE_HELPERS,
+} from "./capabilities-helpers.js";
+export type { ScaleCapability, StyleAesthetic } from "./capabilities-helpers.js";
+
+/** One checked geom-consumption table for mapped style channels. */
+export const STYLE_AESTHETIC_GEOMS = {
+  // blank trains style scales without marks; jitter is sugar for point.
+  size: [
+    "point",
+    "jitter",
+    "count",
+    "text",
+    "dotplot",
+    "pointrange",
+    "sf",
+    "sf_text",
+    "sf_label",
+    "label",
+    "blank",
+    "qq",
+  ],
+  linewidth: [
+    "line",
+    "function",
+    "qq_line",
+    "path",
+    "step",
+    "freqpoly",
+    "rule",
+    "hline",
+    "vline",
+    "abline",
+    "smooth",
+    "quantile",
+    "contour",
+    "boxplot",
+    "violin",
+    "errorbar",
+    "linerange",
+    "pointrange",
+    "crossbar",
+    "rect",
+    "tile",
+    "hex",
+    "bin_2d",
+    "ribbon",
+    "polygon",
+    "segment",
+    "spoke",
+    "curve",
+    "density_2d",
+    "density_2d_filled",
+    "map",
+    "sf",
+    "blank",
+    "rug",
+    "label",
+  ],
+  alpha: [
+    "point",
+    "jitter",
+    "count",
+    "line",
+    "function",
+    "qq",
+    "qq_line",
+    "path",
+    "step",
+    "freqpoly",
+    "col",
+    "bar",
+    "histogram",
+    "area",
+    "rule",
+    "hline",
+    "vline",
+    "abline",
+    "text",
+    "sf_text",
+    "sf_label",
+    "label",
+    "smooth",
+    "quantile",
+    "contour",
+    "boxplot",
+    "violin",
+    "density",
+    "density_2d",
+    "density_2d_filled",
+    "dotplot",
+    "errorbar",
+    "linerange",
+    "pointrange",
+    "crossbar",
+    "rect",
+    "tile",
+    "hex",
+    "bin_2d",
+    "raster",
+    "ribbon",
+    "polygon",
+    "segment",
+    "spoke",
+    "curve",
+    "map",
+    "sf",
+    "blank",
+    "rug",
+  ],
+  shape: ["point", "jitter", "count", "dotplot", "pointrange", "sf", "blank", "qq"],
+  linetype: [
+    "line",
+    "function",
+    "qq_line",
+    "path",
+    "step",
+    "freqpoly",
+    "rule",
+    "hline",
+    "vline",
+    "abline",
+    "smooth",
+    "quantile",
+    "contour",
+    "boxplot",
+    "violin",
+    "errorbar",
+    "linerange",
+    "pointrange",
+    "crossbar",
+    "rect",
+    "tile",
+    "ribbon",
+    "polygon",
+    "segment",
+    "spoke",
+    "curve",
+    "density_2d",
+    "density_2d_filled",
+    "map",
+    "sf",
+    "blank",
+    "rug",
+  ],
+} as const;