refactor(math): update/fix sigmoid() behavior

BREAKING CHANGE: add new bias arg for sigmoid() to satisfy more use cases.
Use sigmoid01() for old behavior.

- add/update docstrings
- add desmos links

packages/math/src/mix.ts

@@ -1,6 +1,13 @@
 import type { FnN, FnN2, FnN3, FnN4, FnN5, FnN6 } from "@thi.ng/api";
 import { EPS, HALF_PI, PI } from "./api";
 
+/**
+ * Linear interpolation without clamping. Computes `a + (b - a) * t`
+ *
+ * @param a - start value
+ * @param b - end value
+ * @param t - interpolation factor [0..1]
+ */
 export const mix: FnN3 = (a, b, t) => a + (b - a) * t;
 
 /**
@@ -146,9 +153,9 @@ export const tangentDiff3 = (
 ) => 0.5 * ((next - curr) / (tc - tb) + (curr - prev) / (tb - ta));
 
 /**
- * HOF interpolator. Takes a timing function `f` and interval `[from,
- * to]`. Returns function which takes normalized time as single arg and
- * returns interpolated value.
+ * HOF interpolator. Takes a timing function `f` and interval `[from,to]`.
+ * Returns function which takes normalized time (in [0,1] range) as single arg
+ * and returns interpolated value.
  *
  * @param f -
  * @param from -
@@ -262,20 +269,34 @@ export const sinc: FnN2 = (k, t) => {
 };
 
 /**
- * Sigmoid function for inputs in [0..1] interval.
+ * Sigmoid function for inputs arounds center bias.
  *
- * @param k -
- * @param t -
+ * @remarks
+ * Updated in v3.0.0 to add bias value to satisfy more use cases. Use
+ * {@link sigmoid01} for old behavior.
+ *
+ * @param bias - center value (for which result = 0.5)
+ * @param k - steepness
+ * @param t - input value
+ */
+export const sigmoid: FnN3 = (bias, k, t) =>
+    t != bias ? 1 / (1 + Math.exp(-k * (t - bias))) : 0.5;
+
+/**
+ * Sigmoid function for inputs in [0..1] interval. Center bias = 0.5.
+ *
+ * @param k - steepness
+ * @param t - input value
  */
-export const sigmoid: FnN2 = (k, t) => 1 / (1 + Math.exp(-k * (2 * t - 1)));
+export const sigmoid01: FnN3 = (k, t) => sigmoid(0.5, k, t);
 
 /**
- * Sigmoid function for inputs in [-1..+1] interval.
+ * Sigmoid function for inputs in [-1..+1] interval. Center bias = 0
  *
  * @param k -
  * @param t -
  */
-export const sigmoid11: FnN2 = (k, t) => 1 / (1 + Math.exp(-k * t));
+export const sigmoid11: FnN2 = (k, t) => sigmoid(0, k, t);
 
 /**
  * Generalized Schlick bias gain curve, based on:

packages/math/src/step.ts

@@ -16,15 +16,15 @@ export const step: FnN2 = (edge, x) => (x < edge ? 0 : 1);
  * @param edge - lower threshold
  * @param edge2 - upper threshold
  * @param x - test value
- * @returns 0, if `x < edge1`, 1 if `x > edge2`, else sigmoid interpolation
+ * @returns 0, if `x < edge1`, 1 if `x > edge2`, else S-curve polynomial interpolation
  */
 export const smoothStep: FnN3 = (edge, edge2, x) => {
     x = clamp01((x - edge) / (edge2 - edge));
     return (3 - 2 * x) * x * x;
 };
 
 /**
- * Similar to {@link smoothStep} but using different polynomial.
+ * Similar to {@link smoothStep} but using different, higher degree polynomial.
  *
  * @param edge -
  * @param edge2 -
@@ -36,13 +36,18 @@ export const smootherStep: FnN3 = (edge, edge2, x) => {
 };
 
 /**
- * Exponential ramp with variable shape, e.g.
+ * Exponential ramp with variable shape
+ *
+ * @remarks
+ * Example configurations:
  *
  * - S-curve: k=8, n=4
  * - Step near 1.0: k=8, n=20
  * - Pulse: k=0.005, n=-10
  * - Ease-in: k=0.5, n=0.25
  *
+ * Interactive graph: https://www.desmos.com/calculator/gcnuyppycz
+ *
  * @param k -
  * @param n -
  * @param x -