more documentation

src/curve.d.ts

@@ -1,8 +1,8 @@
 import type {CurveFactory} from "d3";
 
-export type CurveFunction = CurveFactory;
+type CurveFunction = CurveFactory;
 
-export type CurveName =
+type CurveName =
   | "basis"
   | "basis-closed"
   | "basis-open"
@@ -24,14 +24,86 @@ export type CurveName =
   | "step-after"
   | "step-before";
 
+/** How to interpolate between control points. */
 export type Curve = CurveName | CurveFunction;
 
-export interface CurveOptions {
-  curve?: CurveOptions;
-  tension?: number;
+/** Options for marks that support curves, such as lines and areas. */
+export interface CurveOptions extends CurveAutoOptions {
+  /**
+   * The curve (interpolation) method for connecting adjacent points. One of:
+   *
+   * * *basis* - a cubic basis spline (repeating the end points)
+   * * *basis-open* - an open cubic basis spline
+   * * *basis-closed* - a closed cubic basis spline
+   * * *bump-x* - a Bézier curve with horizontal tangents
+   * * *bump-y* - a Bézier curve with vertical tangents
+   * * *bundle* - a straightened cubic basis spline (suitable for lines only, not areas)
+   * * *cardinal* - a cubic cardinal spline (with one-sided differences at the ends)
+   * * *cardinal-open* - an open cubic cardinal spline
+   * * *cardinal-closed* - an closed cubic cardinal spline
+   * * *catmull-rom* - a cubic Catmull–Rom spline (with one-sided differences at the ends)
+   * * *catmull-rom-open* - an open cubic Catmull–Rom spline
+   * * *catmull-rom-closed* - a closed cubic Catmull–Rom spline
+   * * *linear* - a piecewise linear curve (*i.e.*, straight line segments)
+   * * *linear-closed* - a closed piecewise linear curve (*i.e.*, straight line segments)
+   * * *monotone-x* - a cubic spline that preserves monotonicity in *x*
+   * * *monotone-y* - a cubic spline that preserves monotonicity in *y*
+   * * *natural* - a natural cubic spline
+   * * *step* - a piecewise constant function where *y* changes at the midpoint of *x*
+   * * *step-after* - a piecewise constant function where *y* changes after *x*
+   * * *step-before* - a piecewise constant function where *x* changes after *y*
+   *
+   * If *curve* is a function, it will be invoked with a given CanvasPath
+   * *context* in the same fashion as a [D3 curve
+   * factory](https://github.com/d3/d3-shape/blob/main/README.md#custom-curves).
+   */
+  curve?: Curve;
 }
 
 export interface CurveAutoOptions {
+  /**
+   * The curve (interpolation) method for connecting adjacent points. One of:
+   *
+   * * *basis* - a cubic basis spline (repeating the end points)
+   * * *basis-open* - an open cubic basis spline
+   * * *basis-closed* - a closed cubic basis spline
+   * * *bump-x* - a Bézier curve with horizontal tangents
+   * * *bump-y* - a Bézier curve with vertical tangents
+   * * *bundle* - a straightened cubic basis spline (suitable for lines only, not areas)
+   * * *cardinal* - a cubic cardinal spline (with one-sided differences at the ends)
+   * * *cardinal-open* - an open cubic cardinal spline
+   * * *cardinal-closed* - an closed cubic cardinal spline
+   * * *catmull-rom* - a cubic Catmull–Rom spline (with one-sided differences at the ends)
+   * * *catmull-rom-open* - an open cubic Catmull–Rom spline
+   * * *catmull-rom-closed* - a closed cubic Catmull–Rom spline
+   * * *linear* - a piecewise linear curve (*i.e.*, straight line segments)
+   * * *linear-closed* - a closed piecewise linear curve (*i.e.*, straight line segments)
+   * * *monotone-x* - a cubic spline that preserves monotonicity in *x*
+   * * *monotone-y* - a cubic spline that preserves monotonicity in *y*
+   * * *natural* - a natural cubic spline
+   * * *step* - a piecewise constant function where *y* changes at the midpoint of *x*
+   * * *step-after* - a piecewise constant function where *y* changes after *x*
+   * * *step-before* - a piecewise constant function where *x* changes after *y*
+   * * *auto* (default) - like *linear*, but use the (possibly spherical) projection, if any
+   *
+   * The *auto* curve is typically used in conjunction with a spherical
+   * projection to interpolate along geodesics. If *curve* is a function, it
+   * will be invoked with a given CanvasPath *context* in the same fashion as a
+   * [D3 curve
+   * factory](https://github.com/d3/d3-shape/blob/main/README.md#custom-curves).
+   */
   curve?: Curve | "auto";
+
+  /**
+   * The tension option only has an effect on bundle, cardinal and Catmull–Rom
+   * splines (*bundle*, *cardinal*, *cardinal-open*, *cardinal-closed*,
+   * *catmull-rom*, *catmull-rom-open*, and *catmull-rom-closed*). For bundle
+   * splines, it corresponds to
+   * [beta](https://github.com/d3/d3-shape/blob/main/README.md#curveBundle_beta);
+   * for cardinal splines,
+   * [tension](https://github.com/d3/d3-shape/blob/main/README.md#curveCardinal_tension);
+   * for Catmull–Rom splines,
+   * [alpha](https://github.com/d3/d3-shape/blob/main/README.md#curveCatmullRom_alpha).
+   */
   tension?: number;
 }

src/index.d.ts

@@ -1,12 +1,10 @@
 export * from "./channel.js";
-export * from "./color.js";
 export * from "./context.js";
 export * from "./curve.js";
 export * from "./dimensions.js";
 export * from "./facet.js";
 export * from "./format.js";
 export * from "./inset.js";
-export * from "./interpolate.js";
 export * from "./interval.js";
 export * from "./legends.js";
 export * from "./mark.js";

src/marks/area.d.ts

@@ -1,11 +1,11 @@
 import type {ChannelValue, ChannelValueSpec} from "../channel.js";
-import type {CurveAutoOptions} from "../curve.js";
+import type {CurveOptions} from "../curve.js";
 import type {Data, MarkOptions, RenderableMark} from "../mark.js";
 import type {Reducer} from "../reducer.js";
 import type {BinOptions} from "../transforms/bin.js";
 import type {StackOptions} from "../transforms/stack.js";
 
-export interface AreaOptions extends MarkOptions, StackOptions, CurveAutoOptions {
+export interface AreaOptions extends MarkOptions, StackOptions, CurveOptions {
   x1?: ChannelValueSpec;
   x2?: ChannelValueSpec;
   y1?: ChannelValueSpec;

src/scales.d.ts

@@ -1,10 +1,72 @@
-import type {ColorSchemeName} from "./color.js";
 import type {InsetOptions} from "./inset.js";
-import type {Interpolate} from "./interpolate.js";
 import type {NiceInterval, RangeInterval} from "./interval.js";
 import type {LegendType} from "./legends.js";
 import type {AxisAnchor} from "./marks/axis.js";
 
+/** How to interpolate range values for continuous scales. */
+export type Interpolate =
+  | "number"
+  | "rgb"
+  | "hsl"
+  | "hcl"
+  | "lab"
+  | (<T>(a: T, b: T) => (t: number) => T)
+  | ((t: number) => any);
+
+type ColorSchemeCase =
+  | "Accent"
+  | "Category10"
+  | "Dark2"
+  | "Paired"
+  | "Pastel1"
+  | "Pastel2"
+  | "Set1"
+  | "Set2"
+  | "Set3"
+  | "Tableau10"
+  | "BrBG"
+  | "PRGn"
+  | "PiYG"
+  | "PuOr"
+  | "RdBu"
+  | "RdGy"
+  | "RdYlBu"
+  | "RdYlGn"
+  | "Spectral"
+  | "BuRd"
+  | "BuYlRd"
+  | "Blues"
+  | "Greens"
+  | "Greys"
+  | "Oranges"
+  | "Purples"
+  | "Reds"
+  | "Turbo"
+  | "Viridis"
+  | "Magma"
+  | "Inferno"
+  | "Plasma"
+  | "Cividis"
+  | "Cubehelix"
+  | "Warm"
+  | "Cool"
+  | "BuGn"
+  | "BuPu"
+  | "GnBu"
+  | "OrRd"
+  | "PuBu"
+  | "PuBuGn"
+  | "PuRd"
+  | "RdPu"
+  | "YlGn"
+  | "YlGnBu"
+  | "YlOrBr"
+  | "YlOrRd"
+  | "Rainbow"
+  | "Sinebow";
+
+export type ColorScheme = ColorSchemeCase | (Lowercase<ColorSchemeCase> & Record<never, never>);
+
 export type ScaleName = "x" | "y" | "fx" | "fy" | "r" | "color" | "opacity" | "symbol" | "length";
 
 export type ScaleFunctions = {[key in ScaleName]?: (value: any) => any};
@@ -105,8 +167,84 @@ export interface ScaleOptions extends ScaleDefaults {
   interval?: RangeInterval;
   percent?: boolean;
 
-  // color scale options
-  scheme?: ColorSchemeName;
+  /**
+   * Shorthand for setting the range or interpolate option of a *color* scale.
+   *
+   * Categorical schemes:
+   *
+   * * *Accent*
+   * * *Category10*
+   * * *Dark2*
+   * * *Paired*
+   * * *Pastel1*
+   * * *Pastel2*
+   * * *Set1*
+   * * *Set2*
+   * * *Set3*
+   * * *Tableau10* (default)
+   *
+   * Sequential schemes:
+   *
+   * * *Blues*
+   * * *Greens*
+   * * *Greys*
+   * * *Oranges*
+   * * *Purples*
+   * * *Reds*
+   * * *Turbo* (default)
+   * * *Viridis*
+   * * *Magma*
+   * * *Inferno*
+   * * *Plasma*
+   * * *Cividis*
+   * * *Cubehelix*
+   * * *Warm*
+   * * *Cool*
+   * * *BuGn*
+   * * *BuPu*
+   * * *GnBu*
+   * * *OrRd*
+   * * *PuBu*
+   * * *PuBuGn*
+   * * *PuRd*
+   * * *RdPu*
+   * * *YlGn*
+   * * *YlGnBu*
+   * * *YlOrBr*
+   * * *YlOrRd*
+   *
+   * Diverging schemes:
+   *
+   * * *BrBG*
+   * * *PRGn*
+   * * *PiYG*
+   * * *PuOr*
+   * * *RdBu* (default)
+   * * *RdGy*
+   * * *RdYlBu*
+   * * *RdYlGn*
+   * * *Spectral*
+   * * *BuRd*
+   * * *BuYlRd*
+   *
+   * Cyclical schemes:
+   *
+   * * *Rainbow* (default)
+   * * *Sinebow*
+   */
+  scheme?: ColorScheme;
+
+  /**
+   * For continuous scales: how to interpolate range values.
+   *
+   * * *number* - linear numeric interpolation
+   * * *rgb* - red, green, blue (sRGB)
+   * * *hsl* - hue, saturation, lightness (HSL; cylindrical sRGB)
+   * * *hcl* - hue, chroma, perceptual lightness (CIELCh_ab; cylindrical CIELAB)
+   * * *lab* - perceptual lightness and opponent colors (L\*a\*b\*, CIELAB)
+   * * a function that takes a single argument t in [0, 1]
+   * * a function that takes two arguments a and b to interpolate
+   */
   interpolate?: Interpolate;
 
   // power scale options
@@ -146,27 +284,7 @@ export interface ScaleOptions extends ScaleDefaults {
   line?: boolean;
 }
 
-// TODO greater specificity
-export interface Scale {
-  type: ScaleType;
-  domain: any[];
-  range?: any[];
-  transform?: (t: any) => any;
-  percent?: boolean;
-  unknown?: any;
-  interval?: RangeInterval;
-  interpolate?: Interpolate;
-  clamp?: boolean;
-  pivot?: any;
-  symmetric?: boolean;
-  base?: number;
-  exponent?: number;
-  constant?: number;
-  align?: number;
-  round?: boolean;
-  padding?: number;
-  paddingInner?: number;
-  paddingOuter?: number;
+export interface Scale extends ScaleOptions {
   bandwidth?: number;
   step?: number;
   apply(t: any): any;