@ggts-sh/spec 0.43.0

package/src/scale-reference.ts

@@ -0,0 +1,165 @@
+/**
+ * SCALE_REFERENCE — per-Scale* component API docs for the docs site.
+ *
+ * Catalog data is precomputed from SCALE_CAPABILITIES + SpecDeclarations
+ * (`scripts/gen-reference-catalogs.ts`) so reference pages never load TypeBox.
+ * Shells under packages/svelte/src/lib/scale/ are declaration-only; document
+ * this catalog instead of TypeDoc.
+ */
+import {
+  SCALE_CAPABILITIES,
+  STYLE_ORDINAL_SCALE_HELPERS,
+  scaleCapabilityCamelHelpers,
+  type ScaleCapability,
+} from "./capabilities.js";
+import { SCALE_REFERENCE_DATA } from "./generated/scale-reference-data.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface ScaleParamDoc {
+  readonly name: string;
+  readonly description: string;
+  readonly typeSummary: string;
+  readonly required: boolean;
+}
+
+export type ScaleFamily = ScaleCapability["family"];
+
+/** Canonical aesthetic channel(s) this Scale* component configures. */
+export type ScaleAesthetic =
+  | "x"
+  | "y"
+  | "color"
+  | "fill"
+  | "size"
+  | "linewidth"
+  | "alpha"
+  | "shape"
+  | "linetype";
+
+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();
+}
+
+/** 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();
+}
+
+/**
+ * Complete per-scale API reference. Keys are route slugs
+ * (e.g. color_continuous, x_log10). Precomputed at gen time.
+ */
+export const SCALE_REFERENCE: Readonly<Record<string, ScaleReferenceEntry>> = SCALE_REFERENCE_DATA;
+
+/** Stable sorted list for docs index, search, and inventory. */
+export function scaleReferenceList(): readonly ScaleReferenceEntry[] {
+  return Object.values(SCALE_REFERENCE).toSorted((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/** Primary (non-alias) entries only. */
+export function scaleReferencePrimaries(): readonly ScaleReferenceEntry[] {
+  return scaleReferenceList().filter((e) => e.aliasOf === undefined);
+}
+
+/** Group primaries by family for the landing page. */
+export function scaleReferenceByFamily(): Readonly<
+  Record<ScaleFamily, readonly ScaleReferenceEntry[]>
+> {
+  const groups = {} as Record<ScaleFamily, ScaleReferenceEntry[]>;
+  for (const cap of SCALE_CAPABILITIES) {
+    groups[cap.family] = [];
+  }
+  for (const entry of scaleReferencePrimaries()) {
+    groups[entry.family].push(entry);
+  }
+  for (const family of Object.keys(groups) as ScaleFamily[]) {
+    groups[family] = Object.freeze(
+      groups[family].toSorted((a, b) => a.slug.localeCompare(b.slug)),
+    ) as ScaleReferenceEntry[];
+  }
+  return Object.freeze(groups);
+}
+
+/** Display labels for capability families on the index page. */
+export const SCALE_FAMILY_LABELS: Readonly<Record<ScaleFamily, string>> = Object.freeze({
+  "position-continuous": "Position — continuous",
+  "position-binned": "Position — binned",
+  "position-temporal": "Position — temporal",
+  "position-discrete": "Position — discrete",
+  "color-fill": "Color and fill",
+  "numeric-style": "Size, linewidth, and alpha",
+  "finite-style": "Shape and linetype",
+});
+
+/** Known scale reference slugs (for route entry generation). */
+export function knownScaleSlugs(): readonly string[] {
+  return scaleReferenceList().map((e) => e.slug);
+}

package/src/scale-style-helpers.ts

@@ -0,0 +1,316 @@
+/**
+ * Non-position mapped style scale authoring helpers.
+ * Position and color/fill helpers live in their sibling modules; the stable
+ * public facade re-exports this module from scale-helpers.ts.
+ */
+
+import type { CellValue, GuideSpec, PositiveStyleScaleSpec, Scales } from "./schema.js";
+import type { LinetypeName, PointShapeName } from "./schema-names.js";
+
+// --- mapped numeric and finite-symbol styles --------------------------------
+
+type NumericStyleAesthetic = "size" | "linewidth" | "alpha";
+type FiniteStyleAesthetic = "shape" | "linetype";
+type NumericStyleScaleSpec = PositiveStyleScaleSpec;
+
+/**
+ * Portable size/linewidth config options. `sizeUnit` is size-only at runtime;
+ * it is stripped from alpha helper option types (SequentialStyleScaleOptions).
+ */
+export type NumericStyleScaleOptions = Omit<NumericStyleScaleSpec, "type"> & {
+  sizeUnit?: "area" | "radius" | "area_zero";
+};
+/** Continuous/binned options shared by size, linewidth, and alpha (no sizeUnit). */
+export type SequentialStyleScaleOptions = Omit<
+  NumericStyleScaleOptions,
+  "domainMode" | "onExhaust" | "sizeUnit"
+>;
+/** Size sequential/binned options — may set sizeUnit (#830). */
+export type SizeSequentialStyleScaleOptions = SequentialStyleScaleOptions & {
+  /** Size aesthetic only; runtime ignores this for linewidth. */
+  sizeUnit?: "area" | "radius" | "area_zero";
+};
+export type DiscreteNumericStyleScaleOptions = Pick<
+  NumericStyleScaleSpec,
+  "domain" | "domainMode" | "range" | "reverse" | "naValue" | "unknownValue" | "onExhaust" | "guide"
+>;
+export type TemporalNumericStyleScaleOptions = Omit<SequentialStyleScaleOptions, "temporalKind">;
+export type SizeTemporalNumericStyleScaleOptions = Omit<
+  SizeSequentialStyleScaleOptions,
+  "temporalKind"
+>;
+export type ManualNumericStyleScaleOptions = Pick<
+  NumericStyleScaleSpec,
+  "domain" | "naValue" | "unknownValue" | "guide"
+> & { values: NonNullable<NumericStyleScaleSpec["range"]> };
+export type IdentityNumericStyleScaleOptions = Pick<
+  NumericStyleScaleSpec,
+  "naValue" | "unknownValue" | "guide"
+>;
+export interface FiniteStyleScaleOptions<Output extends string = PointShapeName | LinetypeName> {
+  domain?: readonly CellValue[];
+  domainMode?: "grow" | "data";
+  breaks?: readonly number[];
+  range?: readonly Output[];
+  reverse?: boolean;
+  naValue?: Output;
+  unknownValue?: Output;
+  onExhaust?: "cycle" | "error";
+  labels?: string;
+  guide?: GuideSpec;
+}
+export type DiscreteFiniteStyleScaleOptions<Output extends string = PointShapeName | LinetypeName> =
+  Omit<FiniteStyleScaleOptions<Output>, "breaks" | "labels">;
+export type BinnedFiniteStyleScaleOptions<Output extends string = PointShapeName | LinetypeName> =
+  Omit<FiniteStyleScaleOptions<Output>, "domain" | "domainMode" | "onExhaust"> & {
+    domain?: readonly [number, number];
+  };
+type ShapeDiscreteStyleScaleOptions = DiscreteFiniteStyleScaleOptions<PointShapeName>;
+type ShapeBinnedStyleScaleOptions = BinnedFiniteStyleScaleOptions<PointShapeName>;
+type LinetypeDiscreteStyleScaleOptions = DiscreteFiniteStyleScaleOptions<LinetypeName>;
+type LinetypeBinnedStyleScaleOptions = BinnedFiniteStyleScaleOptions<LinetypeName>;
+export interface ManualFiniteStyleScaleOptions<
+  Output extends string = PointShapeName | LinetypeName,
+> {
+  domain?: readonly CellValue[];
+  values: readonly Output[];
+  naValue?: Output;
+  unknownValue?: Output;
+  guide?: GuideSpec;
+}
+export interface IdentityFiniteStyleScaleOptions<
+  Output extends string = PointShapeName | LinetypeName,
+> {
+  naValue?: Output;
+  unknownValue?: Output;
+  guide?: GuideSpec;
+}
+
+function numericStyleScale(
+  aesthetic: NumericStyleAesthetic,
+  type: "ordinal" | "sequential" | "binned" | "manual" | "identity",
+  options: NumericStyleScaleOptions = {},
+  temporalKind?: "date" | "datetime",
+): Scales {
+  return {
+    [aesthetic]: {
+      type,
+      ...options,
+      ...(temporalKind !== undefined && { temporalKind }),
+    },
+  };
+}
+
+function manualNumericStyleScale(
+  aesthetic: NumericStyleAesthetic,
+  options: ManualNumericStyleScaleOptions,
+): Scales {
+  const { values, ...rest } = options;
+  return numericStyleScale(aesthetic, "manual", { ...rest, range: [...values] });
+}
+
+function finiteStyleScale(
+  aesthetic: FiniteStyleAesthetic,
+  type: "ordinal" | "binned" | "manual" | "identity",
+  options: FiniteStyleScaleOptions = {},
+): Scales {
+  return { [aesthetic]: { type, ...options } };
+}
+
+function manualFiniteStyleScale(
+  aesthetic: FiniteStyleAesthetic,
+  options: ManualFiniteStyleScaleOptions,
+): Scales {
+  const { values, ...rest } = options;
+  return { [aesthetic]: { type: "manual", ...rest, range: [...values] } };
+}
+
+export type SizeAreaScaleOptions = SizeSequentialStyleScaleOptions & {
+  /** Max radius when range is omitted (ggplot2 `max_size`; default 6). */
+  maxSize?: number;
+};
+
+export function scaleSizeContinuous(options: SizeSequentialStyleScaleOptions = {}): Scales {
+  return numericStyleScale("size", "sequential", options);
+}
+export function scaleSizeDiscrete(options: DiscreteNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("size", "ordinal", options);
+}
+export function scaleSizeBinned(options: SizeSequentialStyleScaleOptions = {}): Scales {
+  return numericStyleScale("size", "binned", options);
+}
+export function scaleSizeDate(options: SizeTemporalNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("size", "sequential", options, "date");
+}
+export function scaleSizeDatetime(options: SizeTemporalNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("size", "sequential", options, "datetime");
+}
+export function scaleSizeManual(options: ManualNumericStyleScaleOptions): Scales {
+  return manualNumericStyleScale("size", options);
+}
+export function scaleSizeIdentity(options: IdentityNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("size", "identity", options);
+}
+
+/**
+ * ggplot2 `scale_size_area` — area ∝ value with zero→zero area.
+ * Prefer `maxSize` (or `range: [0, max]`) for the maximum radius.
+ */
+export function scaleSizeArea(options: SizeAreaScaleOptions = {}): Scales {
+  const { maxSize, range, ...rest } = options;
+  const resolvedRange = range === undefined ? [0, maxSize ?? 6] : [...range];
+  return numericStyleScale("size", "sequential", {
+    ...rest,
+    range: resolvedRange,
+    sizeUnit: "area_zero",
+  });
+}
+
+/** ggplot2 `scale_size_binned_area` — binned values mapped with zero→zero area. */
+export function scaleSizeBinnedArea(options: SizeAreaScaleOptions = {}): Scales {
+  const { maxSize, range, ...rest } = options;
+  const resolvedRange = range === undefined ? [0, maxSize ?? 6] : [...range];
+  return numericStyleScale("size", "binned", {
+    ...rest,
+    range: resolvedRange,
+    sizeUnit: "area_zero",
+  });
+}
+
+/** ggplot2 `scale_radius` — map value linearly to radius (not area). */
+export function scaleRadius(options: SizeSequentialStyleScaleOptions = {}): Scales {
+  return numericStyleScale("size", "sequential", {
+    ...options,
+    sizeUnit: "radius",
+  });
+}
+
+/** ggplot2 `scale_size_ordinal` — ordered discrete sizes. */
+export const scaleSizeOrdinal = scaleSizeDiscrete;
+
+export function scaleLinewidthContinuous(options: SequentialStyleScaleOptions = {}): Scales {
+  return numericStyleScale("linewidth", "sequential", options);
+}
+export function scaleLinewidthDiscrete(options: DiscreteNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("linewidth", "ordinal", options);
+}
+export function scaleLinewidthBinned(options: SequentialStyleScaleOptions = {}): Scales {
+  return numericStyleScale("linewidth", "binned", options);
+}
+export function scaleLinewidthDate(options: TemporalNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("linewidth", "sequential", options, "date");
+}
+export function scaleLinewidthDatetime(options: TemporalNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("linewidth", "sequential", options, "datetime");
+}
+export function scaleLinewidthManual(options: ManualNumericStyleScaleOptions): Scales {
+  return manualNumericStyleScale("linewidth", options);
+}
+export function scaleLinewidthIdentity(options: IdentityNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("linewidth", "identity", options);
+}
+
+export function scaleAlphaContinuous(options: SequentialStyleScaleOptions = {}): Scales {
+  return numericStyleScale("alpha", "sequential", options);
+}
+export function scaleAlphaDiscrete(options: DiscreteNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("alpha", "ordinal", options);
+}
+export function scaleAlphaBinned(options: SequentialStyleScaleOptions = {}): Scales {
+  return numericStyleScale("alpha", "binned", options);
+}
+export function scaleAlphaDate(options: TemporalNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("alpha", "sequential", options, "date");
+}
+export function scaleAlphaDatetime(options: TemporalNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("alpha", "sequential", options, "datetime");
+}
+export function scaleAlphaManual(options: ManualNumericStyleScaleOptions): Scales {
+  return manualNumericStyleScale("alpha", options);
+}
+export function scaleAlphaIdentity(options: IdentityNumericStyleScaleOptions = {}): Scales {
+  return numericStyleScale("alpha", "identity", options);
+}
+
+export function scaleShapeDiscrete(options: ShapeDiscreteStyleScaleOptions = {}): Scales {
+  return finiteStyleScale("shape", "ordinal", options);
+}
+export function scaleShapeBinned(options: ShapeBinnedStyleScaleOptions = {}): Scales {
+  return finiteStyleScale("shape", "binned", options);
+}
+export function scaleShapeManual(options: ManualFiniteStyleScaleOptions<PointShapeName>): Scales {
+  return manualFiniteStyleScale("shape", options);
+}
+export function scaleShapeIdentity(
+  options: IdentityFiniteStyleScaleOptions<PointShapeName> = {},
+): Scales {
+  return finiteStyleScale("shape", "identity", options);
+}
+
+export function scaleLinetypeDiscrete(options: LinetypeDiscreteStyleScaleOptions = {}): Scales {
+  return finiteStyleScale("linetype", "ordinal", options);
+}
+export function scaleLinetypeBinned(options: LinetypeBinnedStyleScaleOptions = {}): Scales {
+  return finiteStyleScale("linetype", "binned", options);
+}
+export function scaleLinetypeManual(options: ManualFiniteStyleScaleOptions<LinetypeName>): Scales {
+  return manualFiniteStyleScale("linetype", options);
+}
+export function scaleLinetypeIdentity(
+  options: IdentityFiniteStyleScaleOptions<LinetypeName> = {},
+): Scales {
+  return finiteStyleScale("linetype", "identity", options);
+}
+
+export const scaleSize = scaleSizeContinuous;
+export const scaleLinewidth = scaleLinewidthContinuous;
+export const scaleAlpha = scaleAlphaContinuous;
+export const scaleShape = scaleShapeDiscrete;
+export const scaleLinetype = scaleLinetypeDiscrete;
+// ggplot2 scale_*_ordinal spellings — discrete style already emits type:"ordinal" (#832).
+export const scaleAlphaOrdinal = scaleAlphaDiscrete;
+export const scaleLinewidthOrdinal = scaleLinewidthDiscrete;
+export const scaleShapeOrdinal = scaleShapeDiscrete;
+export const scale_size_continuous = scaleSizeContinuous;
+export const scale_size_discrete = scaleSizeDiscrete;
+export const scale_size_binned = scaleSizeBinned;
+export const scale_size_date = scaleSizeDate;
+export const scale_size_datetime = scaleSizeDatetime;
+export const scale_size_manual = scaleSizeManual;
+export const scale_size_identity = scaleSizeIdentity;
+export const scale_size = scaleSizeContinuous;
+export const scale_size_area = scaleSizeArea;
+export const scale_size_binned_area = scaleSizeBinnedArea;
+export const scale_size_ordinal = scaleSizeOrdinal;
+export const scale_radius = scaleRadius;
+export const scale_linewidth_continuous = scaleLinewidthContinuous;
+export const scale_linewidth_discrete = scaleLinewidthDiscrete;
+export const scale_linewidth_binned = scaleLinewidthBinned;
+export const scale_linewidth_date = scaleLinewidthDate;
+export const scale_linewidth_datetime = scaleLinewidthDatetime;
+export const scale_linewidth_manual = scaleLinewidthManual;
+export const scale_linewidth_identity = scaleLinewidthIdentity;
+/** Bare ggplot2 alias → continuous (#832). */
+export const scale_linewidth = scaleLinewidthContinuous;
+export const scale_linewidth_ordinal = scaleLinewidthOrdinal;
+export const scale_alpha_continuous = scaleAlphaContinuous;
+export const scale_alpha_discrete = scaleAlphaDiscrete;
+export const scale_alpha_binned = scaleAlphaBinned;
+export const scale_alpha_date = scaleAlphaDate;
+export const scale_alpha_datetime = scaleAlphaDatetime;
+export const scale_alpha_manual = scaleAlphaManual;
+export const scale_alpha_identity = scaleAlphaIdentity;
+/** Bare ggplot2 alias → continuous (#832). */
+export const scale_alpha = scaleAlphaContinuous;
+export const scale_alpha_ordinal = scaleAlphaOrdinal;
+export const scale_shape = scaleShapeDiscrete;
+export const scale_shape_discrete = scaleShapeDiscrete;
+export const scale_shape_ordinal = scaleShapeOrdinal;
+export const scale_shape_binned = scaleShapeBinned;
+export const scale_shape_manual = scaleShapeManual;
+export const scale_shape_identity = scaleShapeIdentity;
+export const scale_linetype = scaleLinetypeDiscrete;
+export const scale_linetype_discrete = scaleLinetypeDiscrete;
+export const scale_linetype_binned = scaleLinetypeBinned;
+export const scale_linetype_manual = scaleLinetypeManual;
+export const scale_linetype_identity = scaleLinetypeIdentity;