@ggts-sh/spec 0.43.0

package/src/scale-reference-build.ts

@@ -0,0 +1,222 @@
+/**
+ * SCALE_REFERENCE builder (SpecDeclarations + capabilities). Gen-only:
+ * `scripts/gen-reference-catalogs.ts`. Runtime uses generated/scale-reference-data.ts.
+ */
+import {
+  SCALE_CAPABILITIES,
+  STYLE_ORDINAL_SCALE_HELPERS,
+  scaleCapabilityCamelHelpers,
+} from "./capabilities.js";
+import { classifyColorFillHelper } from "./scale-reference-classify-color.js";
+import { classifyPositionHelper } from "./scale-reference-classify-position.js";
+import { classifyStyleHelper } from "./scale-reference-classify-style.js";
+import {
+  aestheticFromHelper,
+  type HelperMeta,
+  type ScaleAesthetic,
+  type ScaleFamily,
+  type ScaleParamDoc,
+} from "./scale-reference-classify-support.js";
+
+export type {
+  ScaleAesthetic,
+  ScaleFamily,
+  ScaleParamDoc,
+} from "./scale-reference-classify-support.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface ScaleReferenceEntry {
+  /** Helper name, e.g. scaleXContinuous (Colour aliases use Colour spelling). */
+  readonly helper: string;
+  /** Route slug — snake_case stem without the scale prefix (e.g. x_continuous). */
+  readonly slug: string;
+  /** Svelte component export, e.g. ScaleXContinuous. */
+  readonly component: string;
+  readonly family: ScaleFamily;
+  /** Aesthetic channels written by this helper (usually one). */
+  readonly aesthetics: readonly ScaleAesthetic[];
+  /** Canonical post-normalize scale type(s) this helper authors. */
+  readonly scaleType: string;
+  /** Forced transform when the helper pins one (log10/sqrt); else undefined. */
+  readonly transform?: "log10" | "sqrt";
+  /** Forced temporalKind when the helper pins one. */
+  readonly temporalKind?: string;
+  /** Short purpose text for index + detail lede. */
+  readonly summary: string;
+  /** TypeScript options type name (or Omit expression) for the shell props. */
+  readonly optionsType: string;
+  /** Authoring props (schema-derived + helper sugar). */
+  readonly params: readonly ScaleParamDoc[];
+  /**
+   * How this scale interacts with guides: axis for position; legend/colorbar/
+   * colorsteps for style; "none" when guide: "none" is typical.
+   */
+  readonly guide: string;
+  /**
+   * When set, this component is a binding-identical re-export of another
+   * (British Colour spelling or *Ordinal → *Discrete).
+   */
+  readonly aliasOf?: string;
+  /** Alternate component names that re-export this shell. */
+  readonly alsoExportedAs: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// Naming
+// ---------------------------------------------------------------------------
+
+/** scaleXContinuous → ScaleXContinuous */
+export function componentNameForScaleHelper(helper: string): string {
+  if (!helper.startsWith("scale")) {
+    throw new Error(`SCALE_REFERENCE: expected scale* helper, got "${helper}"`);
+  }
+  return "S" + helper.slice(1);
+}
+
+/** scaleXContinuous → x_continuous; scaleColorViridisC → color_viridis_c */
+export function slugForScaleHelper(helper: string): string {
+  const stem = helper.startsWith("scale") ? helper.slice(5) : helper;
+  return stem
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replaceAll(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .toLowerCase();
+}
+
+// ---------------------------------------------------------------------------
+// Per-helper classification dispatch
+// ---------------------------------------------------------------------------
+
+function classifyHelper(helper: string, family: ScaleFamily): HelperMeta {
+  if (
+    family === "position-continuous" ||
+    family === "position-binned" ||
+    family === "position-temporal" ||
+    family === "position-discrete"
+  ) {
+    return classifyPositionHelper(helper, family);
+  }
+  if (family === "color-fill") return classifyColorFillHelper(helper, family);
+  return classifyStyleHelper(helper, family);
+}
+
+// ---------------------------------------------------------------------------
+// Build catalog
+// ---------------------------------------------------------------------------
+
+function familyForHelper(helper: string): ScaleFamily {
+  for (const cap of SCALE_CAPABILITIES) {
+    if ((cap.helpers as readonly string[]).includes(helper)) {
+      return cap.family;
+    }
+  }
+  // Ordinal style aliases live outside the main ledger helper arrays.
+  if ((STYLE_ORDINAL_SCALE_HELPERS as readonly string[]).includes(helper)) {
+    if (helper.includes("Shape") || helper.includes("Linetype")) return "finite-style";
+    return "numeric-style";
+  }
+  // Colour spelling is on the ledger under color-fill.
+  if (helper.includes("Colour")) {
+    return "color-fill";
+  }
+  throw new Error(`SCALE_REFERENCE: helper "${helper}" not in SCALE_CAPABILITIES`);
+}
+
+function primaryHelperForAlias(helper: string): string | undefined {
+  if (helper.includes("Colour")) {
+    return helper.replace("Colour", "Color");
+  }
+  // Style-channel *Ordinal shells re-export *Discrete (#830/#832). Color/fill
+  // scaleColorOrdinal / scaleFillOrdinal are distinct primary helpers.
+  if ((STYLE_ORDINAL_SCALE_HELPERS as readonly string[]).includes(helper)) {
+    return helper.replace(/Ordinal$/, "Discrete");
+  }
+  return undefined;
+}
+
+function buildAlsoExportedAs(primaryHelper: string): readonly string[] {
+  const aliases: string[] = [];
+  // Colour re-exports for color channel only
+  if (primaryHelper.startsWith("scaleColor")) {
+    aliases.push(componentNameForScaleHelper(primaryHelper.replace("Color", "Colour")));
+  }
+  // Ordinal re-exports for discrete style shells
+  if (
+    primaryHelper.endsWith("Discrete") &&
+    (primaryHelper.startsWith("scaleSize") ||
+      primaryHelper.startsWith("scaleLinewidth") ||
+      primaryHelper.startsWith("scaleAlpha") ||
+      primaryHelper.startsWith("scaleShape"))
+  ) {
+    aliases.push(componentNameForScaleHelper(primaryHelper.replace(/Discrete$/, "Ordinal")));
+  }
+  return Object.freeze(aliases);
+}
+
+function buildEntry(helper: string): ScaleReferenceEntry {
+  const family = familyForHelper(helper);
+  const aliasOfHelper = primaryHelperForAlias(helper);
+  const aes = aestheticFromHelper(helper);
+  const meta =
+    aliasOfHelper === undefined
+      ? classifyHelper(helper, family)
+      : classifyHelper(aliasOfHelper, familyForHelper(aliasOfHelper));
+
+  const aesthetics: readonly ScaleAesthetic[] = Object.freeze([aes]);
+  const alsoExportedAs: readonly string[] =
+    aliasOfHelper === undefined ? buildAlsoExportedAs(helper) : Object.freeze([]);
+  const summary =
+    aliasOfHelper === undefined
+      ? meta.summary
+      : helper.includes("Colour")
+        ? `${meta.summary} British Colour spelling — same binding as ${componentNameForScaleHelper(aliasOfHelper)}.`
+        : `${meta.summary} ggplot2 *Ordinal alias — same binding as ${componentNameForScaleHelper(aliasOfHelper)}.`;
+
+  return Object.freeze({
+    helper,
+    slug: slugForScaleHelper(helper),
+    component: componentNameForScaleHelper(helper),
+    family,
+    aesthetics,
+    scaleType: meta.scaleType,
+    ...(meta.transform === undefined ? {} : { transform: meta.transform }),
+    ...(meta.temporalKind === undefined ? {} : { temporalKind: meta.temporalKind }),
+    summary,
+    optionsType: meta.optionsType,
+    params: Object.freeze([...meta.params]),
+    guide: meta.guide,
+    ...(aliasOfHelper === undefined ? {} : { aliasOf: slugForScaleHelper(aliasOfHelper) }),
+    alsoExportedAs,
+  });
+}
+
+/** Primary Scale* helpers (no Colour / Ordinal-only aliases). */
+export function primaryScaleHelpers(): readonly string[] {
+  return scaleCapabilityCamelHelpers();
+}
+
+/**
+ * Every public Scale* surface: primary shells + Colour aliases + Ordinal
+ * style aliases (binding-identical re-exports).
+ */
+export function allScaleHelpers(): readonly string[] {
+  const primary = scaleCapabilityCamelHelpers();
+  const colour = primary
+    .filter((h) => h.startsWith("scaleColor"))
+    .map((h) => h.replace("Color", "Colour"));
+  return [...new Set([...primary, ...colour, ...STYLE_ORDINAL_SCALE_HELPERS])].toSorted();
+}
+
+export function buildScaleReference(): Readonly<Record<string, ScaleReferenceEntry>> {
+  const out: Record<string, ScaleReferenceEntry> = {};
+  for (const helper of allScaleHelpers()) {
+    const entry = buildEntry(helper);
+    if (out[entry.slug] !== undefined) {
+      throw new Error(`SCALE_REFERENCE: duplicate slug "${entry.slug}"`);
+    }
+    out[entry.slug] = entry;
+  }
+  return Object.freeze(out);
+}

package/src/scale-reference-classify-color.ts

@@ -0,0 +1,334 @@
+/**
+ * Color/fill-family classification for the SCALE_REFERENCE builder
+ * (gen-only): continuous, binned, ordinal, manual, identity, transformed,
+ * temporal, and gradient/brewer/distiller/fermenter/viridis/hue/grey
+ * variants.
+ */
+import {
+  aestheticFromHelper,
+  guideFor,
+  paramDocsFromSchema,
+  withGradientStops,
+  withHueGrey,
+  withPaletteDirection,
+  withValues,
+  withViridisOption,
+  type HelperMeta,
+} from "./scale-reference-classify-support.js";
+
+// ---------------------------------------------------------------------------
+// Param key sets per options family (mirrors helper option Pick/Omit types)
+// ---------------------------------------------------------------------------
+
+const COLOR_SEQUENTIAL_KEYS = [
+  "domain",
+  "breaks",
+  "range",
+  "scheme",
+  "reverse",
+  "transform",
+  "oob",
+  "naValue",
+  "unknownValue",
+  "labels",
+  "guide",
+] as const;
+
+const COLOR_TRANSFORMED_KEYS = [
+  "domain",
+  "breaks",
+  "range",
+  "scheme",
+  "reverse",
+  "oob",
+  "naValue",
+  "unknownValue",
+  "labels",
+  "guide",
+] as const;
+
+const COLOR_DISCRETE_KEYS = [
+  "domain",
+  "domainMode",
+  "range",
+  "scheme",
+  "reverse",
+  "naValue",
+  "unknownValue",
+  "onExhaust",
+  "guide",
+] as const;
+
+const COLOR_MANUAL_KEYS = ["domain", "naValue", "unknownValue", "guide"] as const;
+const COLOR_IDENTITY_KEYS = ["naValue", "unknownValue", "guide"] as const;
+const COLOR_TEMPORAL_KEYS = [
+  "domain",
+  "breaks",
+  "range",
+  "scheme",
+  "reverse",
+  "oob",
+  "naValue",
+  "unknownValue",
+  "labels",
+  "guide",
+  "parse",
+  "parseFailure",
+  "timezone",
+  "disambiguation",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Per-helper classification: color / fill
+// ---------------------------------------------------------------------------
+
+type ColorFillFamily = "color-fill";
+
+const colorParams = (keys: readonly string[]) => paramDocsFromSchema("ColorScaleSpec", keys);
+
+type ColorHandler = (helper: string) => HelperMeta | undefined;
+
+function classifyPalette(helper: string): HelperMeta | undefined {
+  const aes = aestheticFromHelper(helper);
+
+  if (helper.includes("Viridis")) {
+    const kind = helper.endsWith("D") ? "ordinal" : helper.endsWith("B") ? "binned" : "sequential";
+    const label =
+      kind === "ordinal"
+        ? "discrete (viridis_d)"
+        : kind === "binned"
+          ? "binned (viridis_b)"
+          : "continuous (viridis_c)";
+    return {
+      optionsType: "ViridisScaleOptions",
+      scaleType: kind,
+      params: withViridisOption(colorParams(COLOR_SEQUENTIAL_KEYS.filter((k) => k !== "scheme"))),
+      guide: guideFor(aes, kind),
+      summary: `Viridis-family ${aes} scale — ${label}.`,
+    };
+  }
+  if (helper.includes("Brewer")) {
+    return {
+      optionsType: "ColorBrewerScaleOptions",
+      scaleType: "ordinal",
+      params: withPaletteDirection(colorParams(COLOR_DISCRETE_KEYS)),
+      guide: guideFor(aes, "ordinal"),
+      summary: `ColorBrewer qualitative ${aes} scale (discrete categories).`,
+    };
+  }
+  if (helper.includes("Distiller")) {
+    return {
+      optionsType: "ColorDistillerScaleOptions",
+      scaleType: "sequential",
+      params: withPaletteDirection(colorParams(COLOR_SEQUENTIAL_KEYS)),
+      guide: guideFor(aes, "sequential"),
+      summary: `ColorBrewer sequential/diverging ${aes} ramp (distiller).`,
+    };
+  }
+  if (helper.includes("Fermenter")) {
+    return {
+      optionsType: "ColorFermenterScaleOptions",
+      scaleType: "binned",
+      params: withPaletteDirection(colorParams(COLOR_SEQUENTIAL_KEYS)),
+      guide: guideFor(aes, "binned"),
+      summary: `ColorBrewer binned ${aes} steps (fermenter).`,
+    };
+  }
+  return undefined;
+}
+
+function classifyGradient2(helper: string): HelperMeta | undefined {
+  const aes = aestheticFromHelper(helper);
+
+  if (helper.includes("Gradient2") || helper.includes("Steps2")) {
+    const binned = helper.includes("Steps");
+    return {
+      optionsType: binned ? "Steps2ScaleOptions" : "Gradient2ScaleOptions",
+      scaleType: binned ? "binned" : "sequential",
+      params: withGradientStops(colorParams(COLOR_SEQUENTIAL_KEYS), binned ? "steps2" : "2"),
+      guide: guideFor(aes, binned ? "binned" : "sequential"),
+      summary: binned
+        ? `Three-stop diverging binned ${aes} steps (low/mid/high).`
+        : `Three-stop diverging continuous ${aes} gradient (low/mid/high).`,
+    };
+  }
+  return undefined;
+}
+
+function classifyGradient(helper: string): HelperMeta | undefined {
+  const aes = aestheticFromHelper(helper);
+
+  if (helper.includes("Gradientn") || helper.includes("Stepsn")) {
+    const binned = helper.includes("Steps");
+    return {
+      optionsType: binned ? "StepsnScaleOptions" : "GradientnScaleOptions",
+      scaleType: binned ? "binned" : "sequential",
+      params: withGradientStops(colorParams(COLOR_SEQUENTIAL_KEYS), binned ? "stepsn" : "n"),
+      guide: guideFor(aes, binned ? "binned" : "sequential"),
+      summary: binned
+        ? `N-stop binned ${aes} steps from an ordered color list.`
+        : `N-stop continuous ${aes} gradient from an ordered color list.`,
+    };
+  }
+  if (helper.includes("Gradient") || helper.endsWith("Steps")) {
+    const binned = helper.endsWith("Steps");
+    return {
+      optionsType: binned ? "StepsScaleOptions" : "GradientScaleOptions",
+      scaleType: binned ? "binned" : "sequential",
+      params: withGradientStops(colorParams(COLOR_SEQUENTIAL_KEYS), binned ? "steps" : "steps"),
+      guide: guideFor(aes, binned ? "binned" : "sequential"),
+      summary: binned
+        ? `Two-stop binned ${aes} steps (low/high).`
+        : `Two-stop continuous ${aes} gradient (low/high).`,
+    };
+  }
+  return undefined;
+}
+
+function classifyNamedPalette(helper: string): HelperMeta | undefined {
+  const aes = aestheticFromHelper(helper);
+
+  if (helper.includes("Hue")) {
+    return {
+      optionsType: "HueScaleOptions",
+      scaleType: "ordinal",
+      params: withHueGrey(colorParams(COLOR_DISCRETE_KEYS), "hue"),
+      guide: guideFor(aes, "ordinal"),
+      summary: `Evenly spaced hue ${aes} palette for discrete categories.`,
+    };
+  }
+  if (helper.includes("Grey") || helper.includes("Gray")) {
+    return {
+      optionsType: "GreyScaleOptions",
+      scaleType: "ordinal",
+      params: withHueGrey(colorParams(COLOR_DISCRETE_KEYS), "grey"),
+      guide: guideFor(aes, "ordinal"),
+      summary: `Grey ramp ${aes} palette for discrete categories.`,
+    };
+  }
+  if (helper.includes("Ordinal")) {
+    return {
+      optionsType: "OrdinalColorScaleOptions",
+      scaleType: "ordinal",
+      params: colorParams(COLOR_DISCRETE_KEYS),
+      guide: guideFor(aes, "ordinal"),
+      summary: `Explicit ordinal ${aes} scale (categories → colors).`,
+    };
+  }
+  return undefined;
+}
+
+function classifyBaseColor(helper: string): HelperMeta | undefined {
+  const aes = aestheticFromHelper(helper);
+
+  if (helper.includes("Log10")) {
+    return {
+      optionsType: "TransformedColorScaleOptions",
+      scaleType: "sequential",
+      transform: "log10",
+      params: colorParams(COLOR_TRANSFORMED_KEYS),
+      guide: guideFor(aes, "sequential"),
+      summary: `Sequential ${aes} scale with log10 pre-training transform.`,
+    };
+  }
+  if (helper.includes("Sqrt")) {
+    return {
+      optionsType: "TransformedColorScaleOptions",
+      scaleType: "sequential",
+      transform: "sqrt",
+      params: colorParams(COLOR_TRANSFORMED_KEYS),
+      guide: guideFor(aes, "sequential"),
+      summary: `Sequential ${aes} scale with sqrt pre-training transform.`,
+    };
+  }
+  if (helper.includes("Datetime")) {
+    return {
+      optionsType: "TemporalColorScaleOptions",
+      scaleType: "sequential",
+      temporalKind: "datetime",
+      params: colorParams(COLOR_TEMPORAL_KEYS),
+      guide: guideFor(aes, "sequential"),
+      summary: `Sequential ${aes} scale trained on datetime values.`,
+    };
+  }
+  if (helper.includes("Date")) {
+    return {
+      optionsType: "TemporalColorScaleOptions",
+      scaleType: "sequential",
+      temporalKind: "date",
+      params: colorParams(COLOR_TEMPORAL_KEYS),
+      guide: guideFor(aes, "sequential"),
+      summary: `Sequential ${aes} scale trained on calendar dates.`,
+    };
+  }
+  if (helper.includes("Manual")) {
+    return {
+      optionsType: "ManualColorScaleOptions",
+      scaleType: "manual",
+      params: withValues(
+        colorParams(COLOR_MANUAL_KEYS),
+        "string[]",
+        "Colors paired positionally with the explicit or trained domain (required).",
+      ),
+      guide: guideFor(aes, "manual"),
+      summary: `Manual ${aes} mapping: domain values paired with explicit colors.`,
+    };
+  }
+  if (helper.includes("Identity")) {
+    return {
+      optionsType: "IdentityColorScaleOptions",
+      scaleType: "identity",
+      params: colorParams(COLOR_IDENTITY_KEYS),
+      guide: guideFor(aes, "identity"),
+      summary: `Identity ${aes} scale: source values are validated #rgb/#rrggbb colors used as-is.`,
+    };
+  }
+  if (helper.includes("Binned")) {
+    return {
+      optionsType: "BinnedColorScaleOptions",
+      scaleType: "binned",
+      params: colorParams(COLOR_SEQUENTIAL_KEYS),
+      guide: guideFor(aes, "binned"),
+      summary: `Binned ${aes} scale: continuous values → ordered color steps.`,
+    };
+  }
+  if (helper.includes("Discrete")) {
+    return {
+      optionsType: "DiscreteColorScaleOptions",
+      scaleType: "ordinal",
+      params: colorParams(COLOR_DISCRETE_KEYS),
+      guide: guideFor(aes, "ordinal"),
+      summary: `Discrete ${aes} scale for categorical data (default ordinal family).`,
+    };
+  }
+  if (helper.includes("Continuous")) {
+    return {
+      optionsType: "SequentialColorScaleOptions",
+      scaleType: "sequential",
+      params: colorParams(COLOR_SEQUENTIAL_KEYS),
+      guide: guideFor(aes, "sequential"),
+      summary: `Continuous sequential ${aes} scale (default continuous color family).`,
+    };
+  }
+  return undefined;
+}
+
+const COLOR_HANDLERS: ColorHandler[] = [
+  classifyPalette,
+  classifyGradient2,
+  classifyGradient,
+  classifyNamedPalette,
+  classifyBaseColor,
+];
+
+export function classifyColorFillHelper(helper: string, _family: ColorFillFamily): HelperMeta {
+  for (const handler of COLOR_HANDLERS) {
+    const meta = handler(helper);
+    if (meta !== undefined) return meta;
+  }
+  const stem = helper.replace(
+    /^scale(Colour|Color|Fill|X|Y|Size|Linewidth|Alpha|Shape|Linetype|Radius)/,
+    "",
+  );
+  throw new Error(`SCALE_REFERENCE: unhandled color/fill helper "${helper}" (stem ${stem})`);
+}