@ggts-sh/spec 0.43.0

package/src/scale-color-helpers.ts

@@ -0,0 +1,263 @@
+/**
+ * Generic non-position color/fill scale helpers + ColorBrewer (#825) +
+ * configuredColorScaleType. Palette families live in sibling modules:
+ * scale-color-viridis.ts, scale-color-stops.ts (gradient + steps),
+ * scale-color-hue-grey.ts. Facade re-exports: scale-helpers.ts.
+ */
+
+import type { ColorScaleSpec, Scales } from "./schema.js";
+import { SEQUENTIAL_SCHEME_NAMES } from "./schema-names.js";
+
+const SEQUENTIAL_SCHEMES = new Set<string>(SEQUENTIAL_SCHEME_NAMES);
+
+/** Resolve family intent encoded by family-specific options before data inference. */
+export function configuredColorScaleType(
+  config: ColorScaleSpec | undefined,
+): ColorScaleSpec["type"] | undefined {
+  if (config === undefined) return undefined;
+  if (config.type !== undefined) return config.type;
+  if (config.scheme !== undefined && config.range === undefined) {
+    return SEQUENTIAL_SCHEMES.has(config.scheme) ? "sequential" : "ordinal";
+  }
+  const sequentialOptions = [
+    config.transform,
+    config.temporalKind,
+    config.parse,
+    config.parseFailure,
+    config.timezone,
+    config.disambiguation,
+    config.breaks,
+    config.oob,
+    config.labels,
+  ];
+  if (sequentialOptions.some((value) => value !== undefined)) {
+    return "sequential";
+  }
+  if (config.domainMode !== undefined || config.onExhaust !== undefined) return "ordinal";
+  return undefined;
+}
+
+// --- generic non-position color/fill families -------------------------------
+
+export type ColorScaleOptions = Omit<ColorScaleSpec, "type">;
+export type SequentialColorScaleOptions = Omit<ColorScaleOptions, "domainMode" | "onExhaust">;
+export type BinnedColorScaleOptions = SequentialColorScaleOptions;
+export type DiscreteColorScaleOptions = Pick<
+  ColorScaleSpec,
+  | "domain"
+  | "domainMode"
+  | "range"
+  | "scheme"
+  | "reverse"
+  | "naValue"
+  | "unknownValue"
+  | "onExhaust"
+  | "guide"
+>;
+export type TransformedColorScaleOptions = Omit<
+  SequentialColorScaleOptions,
+  "transform" | "temporalKind" | "parse" | "parseFailure" | "timezone" | "disambiguation"
+>;
+export type TemporalColorScaleOptions = Omit<
+  SequentialColorScaleOptions,
+  "transform" | "temporalKind"
+>;
+export type ManualColorScaleOptions = Pick<
+  ColorScaleSpec,
+  "domain" | "naValue" | "unknownValue" | "guide"
+> & {
+  /** Colors paired positionally with the explicit or trained domain. */
+  values: NonNullable<ColorScaleSpec["range"]>;
+};
+export type IdentityColorScaleOptions = Pick<ColorScaleSpec, "naValue" | "unknownValue" | "guide">;
+
+type ColorAesthetic = "color" | "fill";
+
+/** Shared PortableSpec builder for color/fill scale helpers (sibling modules). */
+export function colorScale(
+  aesthetic: ColorAesthetic,
+  type: "ordinal" | "sequential" | "binned" | "manual" | "identity",
+  options: ColorScaleOptions = {},
+  forced: {
+    transform?: "log10" | "sqrt";
+    temporalKind?: "date" | "datetime";
+  } = {},
+): Scales {
+  return {
+    [aesthetic]: {
+      type,
+      ...options,
+      ...(forced.transform !== undefined && { transform: forced.transform }),
+      ...(forced.temporalKind !== undefined && { temporalKind: forced.temporalKind }),
+    },
+  };
+}
+
+function manualColorScale(aesthetic: ColorAesthetic, options: ManualColorScaleOptions): Scales {
+  const { values, ...rest } = options;
+  return colorScale(aesthetic, "manual", { ...rest, range: [...values] });
+}
+
+// Color/colour helpers share function identity. American camelCase is the
+// TypeScript-primary spelling; British and snake_case names are exact aliases.
+export function scaleColorContinuous(options: SequentialColorScaleOptions = {}): Scales {
+  return colorScale("color", "sequential", options);
+}
+export function scaleColorDiscrete(options: DiscreteColorScaleOptions = {}): Scales {
+  return colorScale("color", "ordinal", options);
+}
+export function scaleColorBinned(options: BinnedColorScaleOptions = {}): Scales {
+  return colorScale("color", "binned", options);
+}
+export function scaleColorLog10(options: TransformedColorScaleOptions = {}): Scales {
+  return colorScale("color", "sequential", options, { transform: "log10" });
+}
+export function scaleColorSqrt(options: TransformedColorScaleOptions = {}): Scales {
+  return colorScale("color", "sequential", options, { transform: "sqrt" });
+}
+export function scaleColorDate(options: TemporalColorScaleOptions = {}): Scales {
+  return colorScale("color", "sequential", options, { temporalKind: "date" });
+}
+export function scaleColorDatetime(options: TemporalColorScaleOptions = {}): Scales {
+  return colorScale("color", "sequential", options, { temporalKind: "datetime" });
+}
+export function scaleColorManual(options: ManualColorScaleOptions): Scales {
+  return manualColorScale("color", options);
+}
+export function scaleColorIdentity(options: IdentityColorScaleOptions = {}): Scales {
+  return colorScale("color", "identity", options);
+}
+
+/** ggplot2 palette + direction options for ColorBrewer helpers (#825). */
+export type ColorBrewerScaleOptions = DiscreteColorScaleOptions & {
+  /** ColorBrewer palette name (e.g. "Dark2", "Blues"). Maps to `scheme`. */
+  palette?: string;
+  /** `1` (default) or `-1` (reverse). */
+  direction?: 1 | -1;
+};
+
+export type ColorDistillerScaleOptions = SequentialColorScaleOptions & {
+  palette?: string;
+  direction?: 1 | -1;
+};
+
+export type ColorFermenterScaleOptions = BinnedColorScaleOptions & {
+  palette?: string;
+  direction?: 1 | -1;
+};
+
+function withBrewerPalette<T extends { scheme?: string; reverse?: boolean }>(
+  options: T & { palette?: string; direction?: 1 | -1 },
+): T {
+  const { palette, direction, scheme, reverse, ...rest } = options;
+  const resolvedScheme = palette ?? scheme;
+  return {
+    ...rest,
+    ...(resolvedScheme === undefined ? {} : { scheme: resolvedScheme }),
+    ...(direction === -1 || reverse === true ? { reverse: true } : {}),
+  } as T;
+}
+
+/** ggplot2 `scale_color_brewer` — discrete ColorBrewer palette. */
+export function scaleColorBrewer(options: ColorBrewerScaleOptions = {}): Scales {
+  return colorScale("color", "ordinal", withBrewerPalette(options));
+}
+/** ggplot2 `scale_color_distiller` — continuous ColorBrewer ramp. */
+export function scaleColorDistiller(options: ColorDistillerScaleOptions = {}): Scales {
+  return colorScale("color", "sequential", withBrewerPalette(options));
+}
+/** ggplot2 `scale_color_fermenter` — binned ColorBrewer ramp. */
+export function scaleColorFermenter(options: ColorFermenterScaleOptions = {}): Scales {
+  return colorScale("color", "binned", withBrewerPalette(options));
+}
+
+export const scaleColourContinuous = scaleColorContinuous;
+export const scaleColourDiscrete = scaleColorDiscrete;
+export const scaleColourBinned = scaleColorBinned;
+export const scaleColourLog10 = scaleColorLog10;
+export const scaleColourSqrt = scaleColorSqrt;
+export const scaleColourDate = scaleColorDate;
+export const scaleColourDatetime = scaleColorDatetime;
+export const scaleColourManual = scaleColorManual;
+export const scaleColourIdentity = scaleColorIdentity;
+export const scaleColourBrewer = scaleColorBrewer;
+export const scaleColourDistiller = scaleColorDistiller;
+export const scaleColourFermenter = scaleColorFermenter;
+export const scale_color_continuous = scaleColorContinuous;
+export const scale_color_discrete = scaleColorDiscrete;
+export const scale_color_binned = scaleColorBinned;
+export const scale_color_log10 = scaleColorLog10;
+export const scale_color_sqrt = scaleColorSqrt;
+export const scale_color_date = scaleColorDate;
+export const scale_color_datetime = scaleColorDatetime;
+export const scale_color_manual = scaleColorManual;
+export const scale_color_identity = scaleColorIdentity;
+export const scale_color_brewer = scaleColorBrewer;
+export const scale_color_distiller = scaleColorDistiller;
+export const scale_color_fermenter = scaleColorFermenter;
+export const scale_colour_continuous = scaleColorContinuous;
+export const scale_colour_discrete = scaleColorDiscrete;
+export const scale_colour_binned = scaleColorBinned;
+export const scale_colour_log10 = scaleColorLog10;
+export const scale_colour_sqrt = scaleColorSqrt;
+export const scale_colour_date = scaleColorDate;
+export const scale_colour_datetime = scaleColorDatetime;
+export const scale_colour_manual = scaleColorManual;
+export const scale_colour_identity = scaleColorIdentity;
+export const scale_colour_brewer = scaleColorBrewer;
+export const scale_colour_distiller = scaleColorDistiller;
+export const scale_colour_fermenter = scaleColorFermenter;
+
+export function scaleFillContinuous(options: SequentialColorScaleOptions = {}): Scales {
+  return colorScale("fill", "sequential", options);
+}
+export function scaleFillDiscrete(options: DiscreteColorScaleOptions = {}): Scales {
+  return colorScale("fill", "ordinal", options);
+}
+export function scaleFillBinned(options: BinnedColorScaleOptions = {}): Scales {
+  return colorScale("fill", "binned", options);
+}
+export function scaleFillLog10(options: TransformedColorScaleOptions = {}): Scales {
+  return colorScale("fill", "sequential", options, { transform: "log10" });
+}
+export function scaleFillSqrt(options: TransformedColorScaleOptions = {}): Scales {
+  return colorScale("fill", "sequential", options, { transform: "sqrt" });
+}
+export function scaleFillDate(options: TemporalColorScaleOptions = {}): Scales {
+  return colorScale("fill", "sequential", options, { temporalKind: "date" });
+}
+export function scaleFillDatetime(options: TemporalColorScaleOptions = {}): Scales {
+  return colorScale("fill", "sequential", options, { temporalKind: "datetime" });
+}
+export function scaleFillManual(options: ManualColorScaleOptions): Scales {
+  return manualColorScale("fill", options);
+}
+export function scaleFillIdentity(options: IdentityColorScaleOptions = {}): Scales {
+  return colorScale("fill", "identity", options);
+}
+
+/** ggplot2 `scale_fill_brewer`. */
+export function scaleFillBrewer(options: ColorBrewerScaleOptions = {}): Scales {
+  return colorScale("fill", "ordinal", withBrewerPalette(options));
+}
+/** ggplot2 `scale_fill_distiller`. */
+export function scaleFillDistiller(options: ColorDistillerScaleOptions = {}): Scales {
+  return colorScale("fill", "sequential", withBrewerPalette(options));
+}
+/** ggplot2 `scale_fill_fermenter`. */
+export function scaleFillFermenter(options: ColorFermenterScaleOptions = {}): Scales {
+  return colorScale("fill", "binned", withBrewerPalette(options));
+}
+
+export const scale_fill_continuous = scaleFillContinuous;
+export const scale_fill_discrete = scaleFillDiscrete;
+export const scale_fill_binned = scaleFillBinned;
+export const scale_fill_log10 = scaleFillLog10;
+export const scale_fill_sqrt = scaleFillSqrt;
+export const scale_fill_date = scaleFillDate;
+export const scale_fill_datetime = scaleFillDatetime;
+export const scale_fill_manual = scaleFillManual;
+export const scale_fill_identity = scaleFillIdentity;
+export const scale_fill_brewer = scaleFillBrewer;
+export const scale_fill_distiller = scaleFillDistiller;
+export const scale_fill_fermenter = scaleFillFermenter;

package/src/scale-color-hue-grey.ts

@@ -0,0 +1,95 @@
+/**
+ * Hue / grey / ordinal color/fill scale constructors (#829).
+ * Ordinal aliases bind to scaleColorDiscrete / scaleFillDiscrete (same identity).
+ */
+import type { Scales } from "./schema.js";
+import { buildGreyPalette, buildHuePalette } from "./hue-grey-palettes.js";
+import {
+  colorScale,
+  scaleColorDiscrete,
+  scaleFillDiscrete,
+  type DiscreteColorScaleOptions,
+} from "./scale-color-helpers.js";
+
+const HUE_STOPS = 10;
+const GREY_STOPS = 10;
+
+/** scale_*_hue options: discrete + optional HSL-ish h/c/l (bake range if set). */
+export type HueScaleOptions = Omit<DiscreteColorScaleOptions, "scheme" | "range"> & {
+  /** Hue range in degrees [start, end). Default [15, 375). */
+  h?: readonly [number, number];
+  /** Chroma proxy 0–100 → HSL saturation. Default 100. */
+  c?: number;
+  /** Lightness 0–100. Default 65. */
+  l?: number;
+};
+
+/** scale_*_grey / gray options. */
+export type GreyScaleOptions = Omit<DiscreteColorScaleOptions, "scheme" | "range"> & {
+  /** Lightness start in [0, 1]. Default 0.2. */
+  start?: number;
+  /** Lightness end in [0, 1]. Default 0.8. */
+  end?: number;
+};
+
+export type OrdinalColorScaleOptions = DiscreteColorScaleOptions;
+
+function hueConfig(options: HueScaleOptions): DiscreteColorScaleOptions {
+  const { h, c, l, ...rest } = options;
+  if (h !== undefined || c !== undefined || l !== undefined) {
+    return {
+      ...rest,
+      range: buildHuePalette(HUE_STOPS, h ?? [15, 375], c ?? 100, l ?? 65),
+    };
+  }
+  return { ...rest, scheme: "hue" };
+}
+
+function greyConfig(options: GreyScaleOptions): DiscreteColorScaleOptions {
+  const { start, end, ...rest } = options;
+  // Always bake a range — there is no registered "grey"/"gray" scheme name.
+  // scale_*_grey stays portable via explicit stops (start/end still honored).
+  return {
+    ...rest,
+    range: buildGreyPalette(GREY_STOPS, start ?? 0.2, end ?? 0.8),
+  };
+}
+
+export function scaleColorHue(options: HueScaleOptions = {}): Scales {
+  return colorScale("color", "ordinal", hueConfig(options));
+}
+export function scaleColorGrey(options: GreyScaleOptions = {}): Scales {
+  return colorScale("color", "ordinal", greyConfig(options));
+}
+/** Binding-identical American spelling of scaleColorGrey. */
+export const scaleColorGray = scaleColorGrey;
+/** Binding-identical alias of scaleColorDiscrete (ggplot2 scale_*_ordinal). */
+export const scaleColorOrdinal = scaleColorDiscrete;
+
+export function scaleFillHue(options: HueScaleOptions = {}): Scales {
+  return colorScale("fill", "ordinal", hueConfig(options));
+}
+export function scaleFillGrey(options: GreyScaleOptions = {}): Scales {
+  return colorScale("fill", "ordinal", greyConfig(options));
+}
+/** Binding-identical American spelling of scaleFillGrey. */
+export const scaleFillGray = scaleFillGrey;
+/** Binding-identical alias of scaleFillDiscrete. */
+export const scaleFillOrdinal = scaleFillDiscrete;
+
+export const scaleColourHue = scaleColorHue;
+export const scaleColourGrey = scaleColorGrey;
+export const scaleColourGray = scaleColorGray;
+export const scaleColourOrdinal = scaleColorOrdinal;
+export const scale_color_hue = scaleColorHue;
+export const scale_color_grey = scaleColorGrey;
+export const scale_color_gray = scaleColorGray;
+export const scale_color_ordinal = scaleColorOrdinal;
+export const scale_colour_hue = scaleColorHue;
+export const scale_colour_grey = scaleColorGrey;
+export const scale_colour_gray = scaleColorGray;
+export const scale_colour_ordinal = scaleColorOrdinal;
+export const scale_fill_hue = scaleFillHue;
+export const scale_fill_grey = scaleFillGrey;
+export const scale_fill_gray = scaleFillGray;
+export const scale_fill_ordinal = scaleFillOrdinal;

package/src/scale-color-stops.ts

@@ -0,0 +1,177 @@
+/**
+ * Multi-stop color/fill scale constructors: gradient* (#826 continuous) and
+ * steps* (#827 binned). Share default hexes and stop-range resolvers so the
+ * two families stay one edit surface.
+ */
+import type { Scales } from "./schema.js";
+import {
+  colorScale,
+  type BinnedColorScaleOptions,
+  type SequentialColorScaleOptions,
+} from "./scale-color-helpers.js";
+
+// Shared stop defaults (navy→sky continuous; red–light–blue diverging).
+const STOP_DEFAULT_LOW = "#132B43";
+const STOP_DEFAULT_HIGH = "#56B1F7";
+/** ggts diverging defaults (red–light–blue); not claimed as ggplot2 muted(). */
+const STOP2_DEFAULT_LOW = "#B2182B";
+const STOP2_DEFAULT_MID = "#F7F7F7";
+const STOP2_DEFAULT_HIGH = "#2166AC";
+
+/** ggplot2-shaped two-stop continuous colour (default navy → sky). */
+export type GradientScaleOptions = Omit<SequentialColorScaleOptions, "scheme" | "range"> & {
+  low?: string;
+  high?: string;
+};
+
+/**
+ * Diverging three-stop continuous colour.
+ * v1: mid is the center stop of `range` only — no asymmetric domain remapping
+ * (ggplot2 `midpoint` deferred; not accepted so it cannot silently no-op).
+ */
+export type Gradient2ScaleOptions = Omit<SequentialColorScaleOptions, "scheme" | "range"> & {
+  low?: string;
+  mid?: string;
+  high?: string;
+};
+
+/** N-stop continuous colour; requires ≥2 hex stops via colours/colors/values. */
+export type GradientnScaleOptions = Omit<SequentialColorScaleOptions, "scheme" | "range"> & {
+  colours?: readonly string[];
+  colors?: readonly string[];
+  values?: readonly string[];
+};
+
+/** Two-stop stepped continuous colour (default navy → sky). */
+export type StepsScaleOptions = Omit<BinnedColorScaleOptions, "scheme" | "range"> & {
+  low?: string;
+  high?: string;
+};
+
+/**
+ * Three-stop stepped diverging colour.
+ * v1: no `midpoint` param (asymmetric domain remapping deferred).
+ */
+export type Steps2ScaleOptions = Omit<BinnedColorScaleOptions, "scheme" | "range"> & {
+  low?: string;
+  mid?: string;
+  high?: string;
+};
+
+/** N-stop stepped colour; requires ≥2 hex stops via colours/colors/values. */
+export type StepsnScaleOptions = Omit<BinnedColorScaleOptions, "scheme" | "range"> & {
+  colours?: readonly string[];
+  colors?: readonly string[];
+  values?: readonly string[];
+};
+
+type TwoStopOptions = { low?: string; high?: string };
+type ThreeStopOptions = { low?: string; mid?: string; high?: string };
+type NStopOptions = {
+  colours?: readonly string[];
+  colors?: readonly string[];
+  values?: readonly string[];
+};
+
+function twoStopRange<T extends TwoStopOptions>(
+  options: T,
+): Omit<T, "low" | "high"> & { range: string[] } {
+  const { low = STOP_DEFAULT_LOW, high = STOP_DEFAULT_HIGH, ...rest } = options;
+  return { ...rest, range: [low, high] };
+}
+
+function threeStopRange<T extends ThreeStopOptions>(
+  options: T,
+): Omit<T, "low" | "mid" | "high"> & { range: string[] } {
+  const {
+    low = STOP2_DEFAULT_LOW,
+    mid = STOP2_DEFAULT_MID,
+    high = STOP2_DEFAULT_HIGH,
+    ...rest
+  } = options;
+  return { ...rest, range: [low, mid, high] };
+}
+
+function nStopRange<T extends NStopOptions>(
+  options: T,
+  helperLabel: string,
+): Omit<T, "colours" | "colors" | "values"> & { range: string[] } {
+  const { colours, colors, values, ...rest } = options;
+  const stops = colours ?? colors ?? values;
+  if (stops === undefined || stops.length < 2) {
+    throw new Error(
+      `${helperLabel} requires colours/colors/values with at least 2 #rgb/#rrggbb stops.`,
+    );
+  }
+  return { ...rest, range: [...stops] };
+}
+
+// --- gradient / gradient2 / gradientn (#826) --------------------------------
+
+export function scaleColorGradient(options: GradientScaleOptions = {}): Scales {
+  return colorScale("color", "sequential", twoStopRange(options));
+}
+export function scaleColorGradient2(options: Gradient2ScaleOptions = {}): Scales {
+  return colorScale("color", "sequential", threeStopRange(options));
+}
+export function scaleColorGradientn(options: GradientnScaleOptions = {}): Scales {
+  return colorScale("color", "sequential", nStopRange(options, "scale_*_gradientn"));
+}
+
+export function scaleFillGradient(options: GradientScaleOptions = {}): Scales {
+  return colorScale("fill", "sequential", twoStopRange(options));
+}
+export function scaleFillGradient2(options: Gradient2ScaleOptions = {}): Scales {
+  return colorScale("fill", "sequential", threeStopRange(options));
+}
+export function scaleFillGradientn(options: GradientnScaleOptions = {}): Scales {
+  return colorScale("fill", "sequential", nStopRange(options, "scale_*_gradientn"));
+}
+
+export const scaleColourGradient = scaleColorGradient;
+export const scaleColourGradient2 = scaleColorGradient2;
+export const scaleColourGradientn = scaleColorGradientn;
+export const scale_color_gradient = scaleColorGradient;
+export const scale_color_gradient2 = scaleColorGradient2;
+export const scale_color_gradientn = scaleColorGradientn;
+export const scale_colour_gradient = scaleColorGradient;
+export const scale_colour_gradient2 = scaleColorGradient2;
+export const scale_colour_gradientn = scaleColorGradientn;
+export const scale_fill_gradient = scaleFillGradient;
+export const scale_fill_gradient2 = scaleFillGradient2;
+export const scale_fill_gradientn = scaleFillGradientn;
+
+// --- steps / steps2 / stepsn (#827) ----------------------------------------
+
+export function scaleColorSteps(options: StepsScaleOptions = {}): Scales {
+  return colorScale("color", "binned", twoStopRange(options));
+}
+export function scaleColorSteps2(options: Steps2ScaleOptions = {}): Scales {
+  return colorScale("color", "binned", threeStopRange(options));
+}
+export function scaleColorStepsn(options: StepsnScaleOptions = {}): Scales {
+  return colorScale("color", "binned", nStopRange(options, "scale_*_stepsn"));
+}
+
+export function scaleFillSteps(options: StepsScaleOptions = {}): Scales {
+  return colorScale("fill", "binned", twoStopRange(options));
+}
+export function scaleFillSteps2(options: Steps2ScaleOptions = {}): Scales {
+  return colorScale("fill", "binned", threeStopRange(options));
+}
+export function scaleFillStepsn(options: StepsnScaleOptions = {}): Scales {
+  return colorScale("fill", "binned", nStopRange(options, "scale_*_stepsn"));
+}
+
+export const scaleColourSteps = scaleColorSteps;
+export const scaleColourSteps2 = scaleColorSteps2;
+export const scaleColourStepsn = scaleColorStepsn;
+export const scale_color_steps = scaleColorSteps;
+export const scale_color_steps2 = scaleColorSteps2;
+export const scale_color_stepsn = scaleColorStepsn;
+export const scale_colour_steps = scaleColorSteps;
+export const scale_colour_steps2 = scaleColorSteps2;
+export const scale_colour_stepsn = scaleColorStepsn;
+export const scale_fill_steps = scaleFillSteps;
+export const scale_fill_steps2 = scaleFillSteps2;
+export const scale_fill_stepsn = scaleFillStepsn;

package/src/scale-color-viridis.ts

@@ -0,0 +1,99 @@
+/**
+ * Viridis family color/fill scale constructors (#828).
+ * ggplot2 scale_*_viridis_{c,d,b}. Helper-only fields `option` and `direction`
+ * are stripped before PortableSpec; `begin`/`end` deferred.
+ */
+import type { Scales } from "./schema.js";
+import { SEQUENTIAL_SCHEME_NAMES } from "./schema-names.js";
+import {
+  colorScale,
+  type ColorScaleOptions,
+  type DiscreteColorScaleOptions,
+  type SequentialColorScaleOptions,
+} from "./scale-color-helpers.js";
+
+type SequentialSchemeName = (typeof SEQUENTIAL_SCHEME_NAMES)[number];
+
+export type ViridisOptionName = SequentialSchemeName;
+
+/** Shared option surface for scale_*_viridis_* constructors. */
+export type ViridisScaleOptions = {
+  /** Viridis-family map name (default `"viridis"`). Maps to PortableSpec `scheme`. */
+  option?: ViridisOptionName;
+  /**
+   * ggplot2 direction: `1` (default) dark→bright, `-1` reverses the ramp.
+   * Emitted as PortableSpec `reverse: true` when `-1`.
+   */
+  direction?: 1 | -1;
+  reverse?: boolean;
+  domain?: SequentialColorScaleOptions["domain"];
+  range?: SequentialColorScaleOptions["range"];
+  breaks?: SequentialColorScaleOptions["breaks"];
+  labels?: SequentialColorScaleOptions["labels"];
+  oob?: SequentialColorScaleOptions["oob"];
+  naValue?: SequentialColorScaleOptions["naValue"];
+  unknownValue?: SequentialColorScaleOptions["unknownValue"];
+  guide?: SequentialColorScaleOptions["guide"];
+  transform?: SequentialColorScaleOptions["transform"];
+  domainMode?: DiscreteColorScaleOptions["domainMode"];
+  onExhaust?: DiscreteColorScaleOptions["onExhaust"];
+};
+
+const VIRIDIS_OPTIONS = new Set<string>(SEQUENTIAL_SCHEME_NAMES);
+
+function resolveViridisPortable(options: ViridisScaleOptions): ColorScaleOptions {
+  const { option, direction, reverse, ...rest } = options;
+  if (option !== undefined && !VIRIDIS_OPTIONS.has(option)) {
+    throw new Error(
+      `Unknown viridis option "${option}". Expected one of: ${SEQUENTIAL_SCHEME_NAMES.join(", ")}.`,
+    );
+  }
+  const out: ColorScaleOptions = {
+    scheme: option ?? "viridis",
+  };
+  if (rest.domain !== undefined) out.domain = rest.domain;
+  if (rest.range !== undefined) out.range = rest.range;
+  if (rest.breaks !== undefined) out.breaks = rest.breaks;
+  if (rest.labels !== undefined) out.labels = rest.labels;
+  if (rest.oob !== undefined) out.oob = rest.oob;
+  if (rest.naValue !== undefined) out.naValue = rest.naValue;
+  if (rest.unknownValue !== undefined) out.unknownValue = rest.unknownValue;
+  if (rest.guide !== undefined) out.guide = rest.guide;
+  if (rest.transform !== undefined) out.transform = rest.transform;
+  if (rest.domainMode !== undefined) out.domainMode = rest.domainMode;
+  if (rest.onExhaust !== undefined) out.onExhaust = rest.onExhaust;
+  if (reverse === true || direction === -1) out.reverse = true;
+  return out;
+}
+
+export function scaleColorViridisC(options: ViridisScaleOptions = {}): Scales {
+  return colorScale("color", "sequential", resolveViridisPortable(options));
+}
+export function scaleColorViridisD(options: ViridisScaleOptions = {}): Scales {
+  return colorScale("color", "ordinal", resolveViridisPortable(options));
+}
+export function scaleColorViridisB(options: ViridisScaleOptions = {}): Scales {
+  return colorScale("color", "binned", resolveViridisPortable(options));
+}
+export function scaleFillViridisC(options: ViridisScaleOptions = {}): Scales {
+  return colorScale("fill", "sequential", resolveViridisPortable(options));
+}
+export function scaleFillViridisD(options: ViridisScaleOptions = {}): Scales {
+  return colorScale("fill", "ordinal", resolveViridisPortable(options));
+}
+export function scaleFillViridisB(options: ViridisScaleOptions = {}): Scales {
+  return colorScale("fill", "binned", resolveViridisPortable(options));
+}
+
+export const scaleColourViridisC = scaleColorViridisC;
+export const scaleColourViridisD = scaleColorViridisD;
+export const scaleColourViridisB = scaleColorViridisB;
+export const scale_color_viridis_c = scaleColorViridisC;
+export const scale_color_viridis_d = scaleColorViridisD;
+export const scale_color_viridis_b = scaleColorViridisB;
+export const scale_colour_viridis_c = scaleColorViridisC;
+export const scale_colour_viridis_d = scaleColorViridisD;
+export const scale_colour_viridis_b = scaleColorViridisB;
+export const scale_fill_viridis_c = scaleFillViridisC;
+export const scale_fill_viridis_d = scaleFillViridisD;
+export const scale_fill_viridis_b = scaleFillViridisB;