curvy 2.0.0-alpha.2 → 2.0.0-alpha.5

package/dist/curve/quadratic2d.d.ts

@@ -0,0 +1,227 @@
+import type { Interval2d } from '../interval/interval2d';
+import type { TwoDimensional } from '../dimensions';
+import type { Closed, Interval } from '../interval/interval';
+import type { Pipeable } from '../utils';
+import type { QuadraticPolynomial } from '../polynomial/quadratic';
+import type { Decreasing, Increasing, Monotonic } from '../polynomial/traits';
+import type * as Solution from '../solution/solution';
+import type { Vector2 } from '../vector/vector2';
+import type { LinearCurve2d } from './linear2d';
+
+declare const QuadraticCurve2dTypeId: unique symbol;
+type QuadraticCurve2dTypeId = typeof QuadraticCurve2dTypeId;
+
+
+export type { Monotonic, Increasing, Decreasing } from '../polynomial/traits';
+/**
+ * A quadratic curve in 2D space.
+ *
+ * All fields are readonly and immutable, and all operations create new instances.
+ *
+ * The two type parameters carry the trait sets of the curve's per-axis
+ * polynomials. Refiners check monotonicity over the unit interval `[0, 1]` —
+ * the curve's natural parameter domain.
+ *
+ * @since 1.0.0
+ */
+export interface QuadraticCurve2d<out XTraits = unknown, out YTraits = unknown> extends Pipeable, TwoDimensional<QuadraticPolynomial<XTraits>, QuadraticPolynomial<YTraits>> {
+    readonly [QuadraticCurve2dTypeId]: QuadraticCurve2dTypeId;
+}
+/**
+ * Creates a new `QuadraticCurve2d` instance from polynomial parameters.
+ *
+ * @param c0 - The x polynomial.
+ * @param c1 - The y polynomial.
+ * @returns A new `QuadraticCurve2d` instance.
+ * @since 1.0.0
+ */
+export declare const fromPolynomials: (c0: QuadraticPolynomial, c1: QuadraticPolynomial) => QuadraticCurve2d;
+/**
+ * Creates a new `QuadraticCurve2d` instance from monomial coefficient vectors.
+ *
+ * Each argument bundles the per-axis coefficient at the given power: `c0`
+ * holds the x⁰ term, `c1` holds the x¹ term, and so on. The resulting curve
+ * evaluates to `c0 + c1·t + c2·t²` per axis.
+ *
+ * @param c0 - The x⁰ coefficients (x and y).
+ * @param c1 - The x¹ coefficients (x and y).
+ * @param c2 - The x² coefficients (x and y).
+ * @returns A new `QuadraticCurve2d` instance.
+ * @since 2.0.0
+ */
+export declare const fromCoefficients: (c0: Vector2, c1: Vector2, c2: Vector2) => QuadraticCurve2d;
+/**
+ * Creates a new `QuadraticCurve2d` instance from quadratic Bézier control
+ * points.
+ *
+ * The three arguments are the Bernstein-basis control points: `p0` and `p2`
+ * are the curve's endpoints and `p1` is the off-curve control handle. The
+ * implementation converts to the curve's internal monomial form in closed
+ * form.
+ *
+ * @param p0 - The first control point (curve start).
+ * @param p1 - The second control point (control handle).
+ * @param p2 - The third control point (curve end).
+ * @returns A new `QuadraticCurve2d` instance whose curve matches the given Bézier.
+ * @since 2.0.0
+ */
+export declare const fromBezierPoints: (p0: Vector2, p1: Vector2, p2: Vector2) => QuadraticCurve2d;
+/**
+ * Checks if a value is a `QuadraticCurve2d`.
+ *
+ * @param c - The value to check.
+ * @returns `true` if the value is a `QuadraticCurve2d`, `false` otherwise.
+ * @since 1.0.0
+ */
+export declare const isQuadraticCurve2d: (c: unknown) => c is QuadraticCurve2d;
+export declare const solve: {
+    /**
+     * Solves the quadratic curve for a given parameter t.
+     *
+     * @param t - The parameter value.
+     * @returns A function that takes a quadratic curve and returns the point on the curve at parameter t.
+     * @since 1.0.0
+     */
+    (t: number): (c: QuadraticCurve2d) => Vector2;
+    /**
+     * Solves the quadratic curve for a given parameter t.
+     *
+     * @param c - The quadratic curve to solve.
+     * @param t - The parameter value.
+     * @returns The point on the curve at parameter t.
+     * @since 1.0.0
+     */
+    (c: QuadraticCurve2d, t: number): Vector2;
+};
+export declare const length: {
+    /**
+     * Computes the length of the quadratic curve over a given interval.
+     *
+     * @param c - The quadratic curve to compute the length of.
+     * @param i - The interval over which to compute the length.
+     * @returns The length of the quadratic curve over the interval.
+     * @since 1.0.0
+     */
+    (c: QuadraticCurve2d, i: Interval): number;
+    /**
+     * Computes the length of the quadratic curve over a given interval.
+     *
+     * @param i - The interval over which to compute the length.
+     * @returns A function that takes a quadratic curve and returns the length of the curve over the interval.
+     * @since 1.0.0
+     */
+    (i: Interval): (c: QuadraticCurve2d) => number;
+};
+export declare const solveAtX: {
+    /**
+     * Evaluates the curve's y values at a given x. Because the x polynomial is
+     * `Monotonic`, the inverse has at most one solution — at most one y value.
+     *
+     * @param c - The quadratic curve.
+     * @param x - The x coordinate.
+     * @returns Zero or one y values, in t-ascending order.
+     * @since 2.0.0
+     */
+    <XT extends Monotonic, YT>(c: QuadraticCurve2d<XT, YT>, x: number): Solution.AtMostOne<number>;
+    /**
+     * Evaluates the curve's y values at a given x. The result is the y values
+     * the curve passes through where x(t) = the given x — up to two solutions
+     * for a quadratic curve.
+     *
+     * @param c - The quadratic curve.
+     * @param x - The x coordinate.
+     * @returns The y values at x, in t-ascending order.
+     * @since 2.0.0
+     */
+    <XT, YT>(c: QuadraticCurve2d<XT, YT>, x: number): Solution.AtMostTwo<number>;
+    /** @since 2.0.0 */
+    (x: number): {
+        <XT extends Monotonic, YT>(c: QuadraticCurve2d<XT, YT>): Solution.AtMostOne<number>;
+        <XT, YT>(c: QuadraticCurve2d<XT, YT>): Solution.AtMostTwo<number>;
+    };
+};
+export declare const solveAtY: {
+    /**
+     * Evaluates the curve's x values at a given y. Because the y polynomial is
+     * `Monotonic`, the inverse has at most one solution.
+     *
+     * @param c - The quadratic curve.
+     * @param y - The y coordinate.
+     * @returns Zero or one x values, in t-ascending order.
+     * @since 2.0.0
+     */
+    <XT, YT extends Monotonic>(c: QuadraticCurve2d<XT, YT>, y: number): Solution.AtMostOne<number>;
+    /**
+     * Evaluates the curve's x values at a given y. The result is the x values
+     * the curve passes through where y(t) = the given y — up to two solutions
+     * for a quadratic curve.
+     *
+     * @param c - The quadratic curve.
+     * @param y - The y coordinate.
+     * @returns The x values at y, in t-ascending order.
+     * @since 2.0.0
+     */
+    <XT, YT>(c: QuadraticCurve2d<XT, YT>, y: number): Solution.AtMostTwo<number>;
+    /** @since 2.0.0 */
+    (y: number): {
+        <XT, YT extends Monotonic>(c: QuadraticCurve2d<XT, YT>): Solution.AtMostOne<number>;
+        <XT, YT>(c: QuadraticCurve2d<XT, YT>): Solution.AtMostTwo<number>;
+    };
+};
+/**
+ * Computes the derivative of a quadratic curve.
+ *
+ * @param c - The quadratic curve to compute the derivative of.
+ * @returns The derivative of the quadratic curve as a linear curve.
+ * @since 1.0.0
+ */
+export declare const derivative: (c: QuadraticCurve2d) => LinearCurve2d;
+export declare const curvature: {
+    /**
+     * Computes the curvature of the quadratic curve at a given parameter t.
+     *
+     * @param c - The quadratic curve to compute the curvature for.
+     * @param t - The parameter value.
+     * @returns The curvature of the quadratic curve at parameter t.
+     * @since 1.0.0
+     */
+    (c: QuadraticCurve2d, t: number): number;
+    /**
+     * Computes the curvature of the quadratic curve at a given parameter t.
+     *
+     * @param t - The parameter value.
+     * @returns A function that takes a quadratic curve and returns the curvature of the curve at parameter t.
+     * @since 1.0.0
+     */
+    (t: number): (c: QuadraticCurve2d) => number;
+};
+/**
+ * Computes the axis-aligned bounding box of the curve over its parameter
+ * domain `[0, 1]`. Accounts for interior extrema, so the box is tight against
+ * the curve and not just the control polygon.
+ *
+ * @param c - The quadratic curve.
+ * @returns A closed `Box2d` enclosing the curve.
+ * @since 2.0.0
+ */
+export declare const boundingBox: (c: QuadraticCurve2d) => Interval2d<Closed, Closed>;
+/**
+ * Type-narrowing predicate: refines both axes' traits to include `Monotonic`
+ * when both x and y polynomials are monotonic over the unit interval `[0, 1]`.
+ *
+ * For checking only one axis, call the polynomial-level refiner directly:
+ * `QuadraticPolynomial.isMonotonic(curve.x, Interval.unit)`.
+ *
+ * @since 2.0.0
+ */
+export declare const isMonotonic: <XT, YT>(c: QuadraticCurve2d<XT, YT>) => c is QuadraticCurve2d<XT & Monotonic, YT & Monotonic>;
+/** @since 2.0.0 */
+export declare const isIncreasing: <XT, YT>(c: QuadraticCurve2d<XT, YT>) => c is QuadraticCurve2d<XT & Increasing, YT & Increasing>;
+/** @since 2.0.0 */
+export declare const isDecreasing: <XT, YT>(c: QuadraticCurve2d<XT, YT>) => c is QuadraticCurve2d<XT & Decreasing, YT & Decreasing>;
+/** @since 2.0.0 */
+export declare const asMonotonic: <XT, YT>(c: QuadraticCurve2d<XT, YT>) => QuadraticCurve2d<XT & Monotonic, YT & Monotonic>;
+/** @since 2.0.0 */
+export declare const asIncreasing: <XT, YT>(c: QuadraticCurve2d<XT, YT>) => QuadraticCurve2d<XT & Increasing, YT & Increasing>;
+/** @since 2.0.0 */
+export declare const asDecreasing: <XT, YT>(c: QuadraticCurve2d<XT, YT>) => QuadraticCurve2d<XT & Decreasing, YT & Decreasing>;

package/dist/curve/rationalCubic2d.d.ts

@@ -0,0 +1,200 @@
+import type { Pipeable } from '../utils';
+import type { CubicPolynomial } from '../polynomial/cubic';
+import type { Increasing, Monotonic } from '../polynomial/traits';
+import type * as Solution from '../solution/solution';
+import type { Vector2, Weighted } from '../vector/vector2';
+import type { CubicCurve2d } from './cubic2d';
+
+declare const RationalCubicCurve2dTypeId: unique symbol;
+type RationalCubicCurve2dTypeId = typeof RationalCubicCurve2dTypeId;
+declare const RationalCurveTraits: unique symbol;
+type RationalCurveTraits = typeof RationalCurveTraits;
+
+
+export type { Decreasing, Increasing, Monotonic } from '../polynomial/traits';
+export { RationalCurveTraits } from './rationalCubic2d.internal';
+/**
+ * A rational cubic curve in 2D space.
+ *
+ * Represented as three cubic polynomials in the parameter `t`: per-axis
+ * numerators `x`, `y`, and a shared denominator `w`. Evaluation is
+ * `(x(t)/w(t), y(t)/w(t))` — the projection from homogeneous coordinates
+ * back to the plane. With all weights equal at the source (e.g. produced
+ * from a non-rational Bézier with unit weights), `w` is constant and the
+ * curve coincides with a polynomial cubic.
+ *
+ * The two type parameters carry per-axis monotonicity trait brands attached
+ * to the rational functions `x(t)/w(t)` and `y(t)/w(t)`. Unlike
+ * `CubicCurve2d`, traits do not flow through to the underlying polynomials —
+ * monotonicity of a ratio of cubics is not the same property as monotonicity
+ * of either cubic alone, so the brand lives on the curve itself. Constructors
+ * with construction-time monotonicity guarantees (e.g. {@link makeMonotonicEasing})
+ * return curves with `Increasing` brands attached, narrowing downstream
+ * operations like {@link solveAtX} to single-solution returns.
+ *
+ * All fields are readonly and immutable, and all operations create new instances.
+ *
+ * @since 2.0.0
+ */
+export interface RationalCubicCurve2d<out XTraits = unknown, out YTraits = unknown> extends Pipeable {
+    readonly [RationalCubicCurve2dTypeId]: RationalCubicCurve2dTypeId;
+    readonly [RationalCurveTraits]: [XTraits, YTraits];
+    readonly x: CubicPolynomial;
+    readonly y: CubicPolynomial;
+    readonly w: CubicPolynomial;
+}
+/**
+ * Checks if a value is a `RationalCubicCurve2d`.
+ *
+ * @param c - The value to check.
+ * @returns `true` if the value is a `RationalCubicCurve2d`, `false` otherwise.
+ * @since 2.0.0
+ */
+export declare const isRationalCubicCurve2d: (c: unknown) => c is RationalCubicCurve2d;
+/**
+ * Creates a new `RationalCubicCurve2d` from per-axis numerator polynomials
+ * and a shared denominator polynomial.
+ *
+ * @param x - The x numerator polynomial.
+ * @param y - The y numerator polynomial.
+ * @param w - The shared denominator polynomial (must be non-zero on `[0, 1]`).
+ * @returns A new `RationalCubicCurve2d` instance.
+ * @since 2.0.0
+ */
+export declare const fromPolynomials: (x: CubicPolynomial, y: CubicPolynomial, w: CubicPolynomial) => RationalCubicCurve2d;
+/**
+ * Creates a new `RationalCubicCurve2d` from four weighted cubic Bézier
+ * control points. The four control points are lifted to homogeneous form
+ * `(w·x, w·y, w)` and the cubic Bernstein basis is expanded into per-channel
+ * monomial coefficients, yielding the curve's `x`, `y`, and `w` polynomials.
+ *
+ * @param p0 - The first weighted control point (curve start).
+ * @param p1 - The second weighted control point (start handle).
+ * @param p2 - The third weighted control point (end handle).
+ * @param p3 - The fourth weighted control point (curve end).
+ * @returns A new `RationalCubicCurve2d` instance.
+ * @since 2.0.0
+ */
+export declare const fromBezierPoints: (p0: Weighted, p1: Weighted, p2: Weighted, p3: Weighted) => RationalCubicCurve2d;
+/**
+ * Creates a guaranteed-monotonic rational cubic easing curve via Gregory-
+ * Delbourgo style construction. The result interpolates `(0, 0)` and
+ * `(1, 1)` with the given endpoint slopes, with `x(t) = t` pinned linearly
+ * and a rational cubic numerator for `y(t)`. Monotonicity of `y(t)` is
+ * verified rigorously at construction (degree-3 polynomial sign analysis);
+ * the returned curve is branded `<Increasing, Increasing>` so that
+ * {@link solveAtX} returns `Solution.AtMostOne<number>` without further
+ * trait refinement.
+ *
+ * For input slope combinations that the default Gregory-Delbourgo
+ * construction cannot accommodate (typically when one slope is large while
+ * the other is small), construction throws. Useful operating range is
+ * roughly `m₀, m₁ ∈ [0, 2]` with `m₀ + m₁ ≲ 3`; smoothstep (`0, 0`) and
+ * linear (`1, 1`) fall out as special cases.
+ *
+ * @param startSlope - The easing function's slope at the start (`dy/dx` at `x = 0`); must be finite and non-negative.
+ * @param endSlope - The easing function's slope at the end (`dy/dx` at `x = 1`); must be finite and non-negative.
+ * @returns A monotone-by-construction rational cubic easing curve.
+ * @throws When slopes are negative, non-finite, or produce a non-monotonic curve under the default construction.
+ * @since 2.0.0
+ */
+export declare const makeMonotonicEasing: (startSlope: number, endSlope: number) => RationalCubicCurve2d<Increasing, Increasing>;
+export declare const solve: {
+    /**
+     * Evaluates the rational cubic curve at parameter `t`. Returns
+     * `(x(t)/w(t), y(t)/w(t))` — three Horner evaluations and two divisions.
+     *
+     * @param c - The curve to evaluate.
+     * @param t - The parameter value.
+     * @returns The point on the curve at parameter `t`.
+     * @since 2.0.0
+     */
+    (c: RationalCubicCurve2d, t: number): Vector2;
+    /**
+     * Evaluates the rational cubic curve at parameter `t`.
+     *
+     * @param t - The parameter value.
+     * @returns A function that takes a curve and returns the point at `t`.
+     * @since 2.0.0
+     */
+    (t: number): (c: RationalCubicCurve2d) => Vector2;
+};
+export declare const solveAtX: {
+    /**
+     * Evaluates the curve's y values at a given x. Because the curve's x axis
+     * carries the `Monotonic` brand, the inverse has at most one solution.
+     *
+     * @param c - The rational cubic curve with monotonic x.
+     * @param x - The x coordinate.
+     * @returns Zero or one y values.
+     * @since 2.0.0
+     */
+    <XT extends Monotonic, YT>(c: RationalCubicCurve2d<XT, YT>, x: number): Solution.AtMostOne<number>;
+    /**
+     * Evaluates the curve's y values at a given x. Up to three solutions —
+     * `(X(t) - x·W(t))` is a cubic polynomial in `t`.
+     *
+     * @param c - The rational cubic curve.
+     * @param x - The x coordinate.
+     * @returns The y values at x, in t-ascending order.
+     * @since 2.0.0
+     */
+    <XT, YT>(c: RationalCubicCurve2d<XT, YT>, x: number): Solution.AtMostThree<number>;
+    /** @since 2.0.0 */
+    (x: number): {
+        <XT extends Monotonic, YT>(c: RationalCubicCurve2d<XT, YT>): Solution.AtMostOne<number>;
+        <XT, YT>(c: RationalCubicCurve2d<XT, YT>): Solution.AtMostThree<number>;
+    };
+};
+export declare const solveAtY: {
+    /**
+     * Evaluates the curve's x values at a given y. Because the curve's y axis
+     * carries the `Monotonic` brand, the inverse has at most one solution.
+     *
+     * @param c - The rational cubic curve with monotonic y.
+     * @param y - The y coordinate.
+     * @returns Zero or one x values.
+     * @since 2.0.0
+     */
+    <XT, YT extends Monotonic>(c: RationalCubicCurve2d<XT, YT>, y: number): Solution.AtMostOne<number>;
+    /**
+     * Evaluates the curve's x values at a given y. Up to three solutions.
+     *
+     * @param c - The rational cubic curve.
+     * @param y - The y coordinate.
+     * @returns The x values at y, in t-ascending order.
+     * @since 2.0.0
+     */
+    <XT, YT>(c: RationalCubicCurve2d<XT, YT>, y: number): Solution.AtMostThree<number>;
+    /** @since 2.0.0 */
+    (y: number): {
+        <XT, YT extends Monotonic>(c: RationalCubicCurve2d<XT, YT>): Solution.AtMostOne<number>;
+        <XT, YT>(c: RationalCubicCurve2d<XT, YT>): Solution.AtMostThree<number>;
+    };
+};
+export declare const approximateAsCubicCurves: {
+    /**
+     * Approximates the rational cubic as a sequence of polynomial cubic curves
+     * via recursive subdivision. At each level a candidate polynomial cubic is
+     * built by projecting the segment's homogeneous Bézier control points to
+     * 2D; if the candidate's midpoint deviates from the true rational midpoint
+     * by more than `tolerance`, the segment is split at `t = 0.5` and the
+     * procedure recurses on each half. Returns a non-empty array; for a curve
+     * that is already polynomial (uniform weights) the result is a single
+     * exact segment.
+     *
+     * @param c - The rational cubic curve to approximate.
+     * @param tolerance - Maximum allowed midpoint deviation; must be positive.
+     * @returns A sequence of polynomial cubic curves covering the input.
+     * @since 2.0.0
+     */
+    (c: RationalCubicCurve2d, tolerance: number): ReadonlyArray<CubicCurve2d>;
+    /**
+     * Approximates the rational cubic as a sequence of polynomial cubic curves.
+     *
+     * @param tolerance - Maximum allowed midpoint deviation; must be positive.
+     * @returns A function that takes a curve and returns its polynomial approximation.
+     * @since 2.0.0
+     */
+    (tolerance: number): (c: RationalCubicCurve2d) => ReadonlyArray<CubicCurve2d>;
+};

package/dist/dimensions.d.ts

@@ -0,0 +1,23 @@
+export type TwoDimensionalIndex = 0 | 1;
+export type TwoDimensionalComponent = 'x' | 'y';
+export interface TwoDimensional<out T1, out T2 = T1> {
+    readonly x: T1;
+    readonly y: T2;
+    readonly 0: T1;
+    readonly 1: T2;
+}
+export type ThreeDimensionalIndex = TwoDimensionalIndex | 2;
+export type ThreeDimensionalComponent = TwoDimensionalComponent | 'z';
+export interface ThreeDimensional<out T1, out T2 = T1, out T3 = T2> extends TwoDimensional<T1, T2> {
+    readonly z: T3;
+    readonly 2: T3;
+}
+export type FourDimensionalIndex = ThreeDimensionalIndex | 3;
+export type FourDimensionalComponent = ThreeDimensionalComponent | 'w';
+export interface FourDimensional<out T1, out T2 = T1, out T3 = T2, out T4 = T3> extends ThreeDimensional<T1, T2, T3> {
+    readonly w: T4;
+    readonly 3: T4;
+}
+export declare const toTwoDimensionalIndex: (input: TwoDimensionalIndex | TwoDimensionalComponent) => TwoDimensionalIndex;
+export declare const toThreeDimensionalIndex: (input: ThreeDimensionalIndex | ThreeDimensionalComponent) => ThreeDimensionalIndex;
+export declare const toFourDimensionalIndex: (input: FourDimensionalIndex | FourDimensionalComponent) => FourDimensionalIndex;

package/dist/interval/index.d.ts

@@ -0,0 +1,6 @@
+import * as IntervalNs from './interval';
+import * as Interval2dNs from './interval2d';
+export { IntervalNs as Interval };
+export type Interval = IntervalNs.Interval;
+export { Interval2dNs as Interval2d };
+export type Interval2d = Interval2dNs.Interval2d;

package/dist/interval/index.mjs

@@ -1,3 +1,3 @@
-import { s as interval_exports } from "../shared/interval-05CR6eBf.mjs";
-import { t as interval2d_exports } from "../shared/interval2d-8IBZnUOq.mjs";
+import { s as interval_exports } from "../shared/interval-X1EYuf-T.mjs";
+import { t as interval2d_exports } from "../shared/interval2d-ca0J1NMr.mjs";
 export { interval_exports as Interval, interval2d_exports as Interval2d };