@flighthq/path 0.1.0

package/src/getPathContourLengths.test.ts

@@ -0,0 +1,51 @@
+import { getPathContourLengths } from './getPathContourLengths';
+import { getPathLength } from './getPathLength';
+import { appendPathClose, appendPathLineTo, appendPathMoveTo, appendPathRectangle, createPath } from './path';
+
+describe('getPathContourLengths', () => {
+  it('returns an empty array for an empty path', () => {
+    expect(getPathContourLengths(createPath())).toStrictEqual([]);
+  });
+
+  it('returns a single length matching getPathLength for a single contour', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    appendPathLineTo(path, 100, 50);
+    const lengths = getPathContourLengths(path);
+    expect(lengths).toHaveLength(1);
+    expect(lengths[0]).toBeCloseTo(getPathLength(path));
+  });
+
+  it('returns per-contour lengths for a multi-contour path', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 30, 0);
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 0, 40);
+    const lengths = getPathContourLengths(path);
+    expect(lengths).toHaveLength(2);
+    expect(lengths[0]).toBeCloseTo(30);
+    expect(lengths[1]).toBeCloseTo(40);
+  });
+
+  it('accounts for closed contours', () => {
+    const path = createPath();
+    appendPathRectangle(path, 0, 0, 100, 50);
+    const lengths = getPathContourLengths(path);
+    expect(lengths).toHaveLength(1);
+    expect(lengths[0]).toBeCloseTo(300);
+  });
+
+  it('sums per-contour lengths to match total getPathLength', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 10, 0);
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 0, 20);
+    appendPathClose(path);
+    const lengths = getPathContourLengths(path);
+    const sum = lengths.reduce((s, l) => s + l, 0);
+    expect(sum).toBeCloseTo(getPathLength(path));
+  });
+});

package/src/getPathLength.test.ts

@@ -0,0 +1,33 @@
+import { getPathLength } from './getPathLength';
+import { appendPathLineTo, appendPathMoveTo, appendPathRectangle, createPath } from './path';
+
+describe('getPathLength', () => {
+  it('returns 0 for an empty path', () => {
+    expect(getPathLength(createPath())).toBe(0);
+  });
+
+  it('returns the correct length of a straight line', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 30, 40);
+    // Euclidean: sqrt(30^2 + 40^2) = 50
+    expect(getPathLength(path)).toBeCloseTo(50);
+  });
+
+  it('returns the perimeter of a rectangle (excluding the closing segment)', () => {
+    const path = createPath();
+    appendPathRectangle(path, 0, 0, 100, 50);
+    // Perimeter of 100x50 rectangle: 2*(100+50)=300. The flattenPath closes with a segment back
+    // to the start, so the total is 300.
+    expect(getPathLength(path)).toBeCloseTo(300);
+  });
+
+  it('sums lengths across multiple subpaths', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 10, 0); // length 10
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 0, 5); // length 5
+    expect(getPathLength(path)).toBeCloseTo(15);
+  });
+});

package/src/getPathNearestPoint.test.ts

@@ -0,0 +1,64 @@
+import { getPathNearestPoint } from './getPathNearestPoint';
+import { appendPathCircle, appendPathLineTo, appendPathMoveTo, createPath } from './path';
+
+describe('getPathNearestPoint', () => {
+  it('returns -1 for an empty path', () => {
+    const out = { x: 0, y: 0 };
+    expect(getPathNearestPoint(createPath(), 5, 5, out)).toBe(-1);
+  });
+
+  it('returns 0 for a point on the path', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    const out = { x: 0, y: 0 };
+    const dist = getPathNearestPoint(path, 50, 0, out);
+    expect(dist).toBeCloseTo(0);
+    expect(out.x).toBeCloseTo(50);
+    expect(out.y).toBeCloseTo(0);
+  });
+
+  it('returns the perpendicular distance for a point off the path', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    const out = { x: 0, y: 0 };
+    const dist = getPathNearestPoint(path, 50, 30, out);
+    expect(dist).toBeCloseTo(30);
+    expect(out.x).toBeCloseTo(50);
+    expect(out.y).toBeCloseTo(0);
+  });
+
+  it('picks the closest contour in a multi-contour path', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    appendPathMoveTo(path, 0, 10);
+    appendPathLineTo(path, 100, 10);
+    const out = { x: 0, y: 0 };
+    const dist = getPathNearestPoint(path, 50, 8, out);
+    expect(dist).toBeCloseTo(2);
+    expect(out.y).toBeCloseTo(10);
+  });
+
+  it('clamps to an endpoint when the projection falls outside the segment', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 10, 0);
+    appendPathLineTo(path, 90, 0);
+    const out = { x: 0, y: 0 };
+    const dist = getPathNearestPoint(path, 0, 0, out);
+    expect(dist).toBeCloseTo(10);
+    expect(out.x).toBeCloseTo(10);
+    expect(out.y).toBeCloseTo(0);
+  });
+
+  it('works with curved paths', () => {
+    const path = createPath();
+    appendPathCircle(path, 0, 0, 50);
+    const out = { x: 0, y: 0 };
+    const dist = getPathNearestPoint(path, 100, 0, out);
+    expect(dist).toBeCloseTo(50, 0);
+    expect(out.x).toBeCloseTo(50, 0);
+    expect(out.y).toBeCloseTo(0, 0);
+  });
+});

package/src/getPathPointAtDistance.test.ts

@@ -0,0 +1,94 @@
+import { getPathPointAtDistance, getPathPositionAtDistance, getPathTangentAtDistance } from './getPathPointAtDistance';
+import { appendPathLineTo, appendPathMoveTo, createPath } from './path';
+
+describe('getPathPointAtDistance', () => {
+  it('returns false for an empty path', () => {
+    const out = { x: 0, y: 0 };
+    expect(getPathPointAtDistance(createPath(), 0, out)).toBe(false);
+  });
+
+  it('returns the start point at distance 0', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 5, 10);
+    appendPathLineTo(path, 15, 10);
+    const out = { x: 0, y: 0 };
+    getPathPointAtDistance(path, 0, out);
+    expect(out.x).toBeCloseTo(5);
+    expect(out.y).toBeCloseTo(10);
+  });
+
+  it('interpolates to the midpoint of a segment', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    const out = { x: 0, y: 0 };
+    getPathPointAtDistance(path, 50, out);
+    expect(out.x).toBeCloseTo(50);
+    expect(out.y).toBeCloseTo(0);
+  });
+
+  it('clamps to the end when distance exceeds total length', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 10, 0);
+    const out = { x: 0, y: 0 };
+    getPathPointAtDistance(path, 1000, out);
+    expect(out.x).toBeCloseTo(10);
+    expect(out.y).toBeCloseTo(0);
+  });
+
+  it('clamps to start when distance is negative', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 5, 5);
+    appendPathLineTo(path, 15, 5);
+    const out = { x: 0, y: 0 };
+    getPathPointAtDistance(path, -10, out);
+    expect(out.x).toBeCloseTo(5);
+    expect(out.y).toBeCloseTo(5);
+  });
+});
+
+describe('getPathPositionAtDistance', () => {
+  it('returns both point and tangent simultaneously', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    const pt = { x: 0, y: 0 };
+    const tan = { x: 0, y: 0 };
+    const result = getPathPositionAtDistance(path, 50, pt, tan);
+    expect(result).toBe(true);
+    expect(pt.x).toBeCloseTo(50);
+    expect(pt.y).toBeCloseTo(0);
+    expect(tan.x).toBeCloseTo(1);
+    expect(tan.y).toBeCloseTo(0);
+  });
+});
+
+describe('getPathTangentAtDistance', () => {
+  it('returns (1,0) as default tangent for empty path', () => {
+    const out = { x: 0, y: 0 };
+    getPathTangentAtDistance(createPath(), 0, out);
+    expect(out.x).toBeCloseTo(1);
+    expect(out.y).toBeCloseTo(0);
+  });
+
+  it('returns a unit tangent along a horizontal line', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    const out = { x: 0, y: 0 };
+    getPathTangentAtDistance(path, 50, out);
+    expect(out.x).toBeCloseTo(1);
+    expect(out.y).toBeCloseTo(0);
+  });
+
+  it('returns a unit tangent along a vertical line', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 0, 100);
+    const out = { x: 0, y: 0 };
+    getPathTangentAtDistance(path, 50, out);
+    expect(out.x).toBeCloseTo(0);
+    expect(out.y).toBeCloseTo(1);
+  });
+});

package/src/getPathSegmentAtParameter.test.ts

@@ -0,0 +1,178 @@
+import {
+  getCubicBezierPoint,
+  getCubicBezierTangent,
+  getPathSegmentPointAtParameter,
+  getPathSegmentTangentAtParameter,
+  getQuadraticBezierPoint,
+  getQuadraticBezierTangent,
+} from './getPathSegmentAtParameter';
+import { appendPathCubicCurveTo, appendPathCurveTo, appendPathLineTo, appendPathMoveTo, createPath } from './path';
+
+describe('getCubicBezierPoint', () => {
+  it('returns the start point at t=0', () => {
+    const out = { x: 0, y: 0 };
+    getCubicBezierPoint(1, 2, 3, 4, 5, 6, 7, 8, 0, out);
+    expect(out.x).toBeCloseTo(1);
+    expect(out.y).toBeCloseTo(2);
+  });
+
+  it('returns the end point at t=1', () => {
+    const out = { x: 0, y: 0 };
+    getCubicBezierPoint(1, 2, 3, 4, 5, 6, 7, 8, 1, out);
+    expect(out.x).toBeCloseTo(7);
+    expect(out.y).toBeCloseTo(8);
+  });
+
+  it('interpolates a straight cubic at midpoint', () => {
+    // Straight line P0=(0,0), C1=(1,0), C2=(2,0), P1=(3,0)
+    const out = { x: 0, y: 0 };
+    getCubicBezierPoint(0, 0, 1, 0, 2, 0, 3, 0, 0.5, out);
+    expect(out.x).toBeCloseTo(1.5);
+    expect(out.y).toBeCloseTo(0);
+  });
+});
+
+describe('getCubicBezierTangent', () => {
+  it('returns the forward tangent at t=0 (C1 - P0)', () => {
+    const out = { x: 0, y: 0 };
+    getCubicBezierTangent(0, 0, 3, 0, 6, 0, 9, 0, 0, out);
+    // B'(0) = 3*(C1-P0) = 3*(3,0) = (9,0)
+    expect(out.x).toBeCloseTo(9);
+    expect(out.y).toBeCloseTo(0);
+  });
+
+  it('returns the backward tangent at t=1 (P1 - C2)', () => {
+    const out = { x: 0, y: 0 };
+    getCubicBezierTangent(0, 0, 0, 0, 6, 0, 9, 0, 1, out);
+    // B'(1) = 3*(P1-C2) = 3*(9-6,0) = (9,0)
+    expect(out.x).toBeCloseTo(9);
+    expect(out.y).toBeCloseTo(0);
+  });
+});
+
+describe('getPathSegmentPointAtParameter', () => {
+  it('returns false for out-of-range segment index', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 1, 0);
+    const out = { x: 0, y: 0 };
+    expect(getPathSegmentPointAtParameter(path, 5, 0.5, out)).toBe(false);
+  });
+
+  it('evaluates midpoint of a line segment', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 10, 0);
+    const out = { x: 0, y: 0 };
+    expect(getPathSegmentPointAtParameter(path, 0, 0.5, out)).toBe(true);
+    expect(out.x).toBeCloseTo(5);
+    expect(out.y).toBeCloseTo(0);
+  });
+
+  it('evaluates start and end of a line segment', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 2, 3);
+    appendPathLineTo(path, 8, 9);
+    const start = { x: 0, y: 0 };
+    const end = { x: 0, y: 0 };
+    getPathSegmentPointAtParameter(path, 0, 0, start);
+    getPathSegmentPointAtParameter(path, 0, 1, end);
+    expect(start.x).toBeCloseTo(2);
+    expect(start.y).toBeCloseTo(3);
+    expect(end.x).toBeCloseTo(8);
+    expect(end.y).toBeCloseTo(9);
+  });
+
+  it('selects the correct segment by index in a multi-segment path', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 10, 0); // segment 0
+    appendPathLineTo(path, 10, 10); // segment 1
+    appendPathLineTo(path, 0, 10); // segment 2
+    const out = { x: 0, y: 0 };
+    getPathSegmentPointAtParameter(path, 1, 0.5, out);
+    expect(out.x).toBeCloseTo(10);
+    expect(out.y).toBeCloseTo(5);
+  });
+
+  it('evaluates midpoint of a quadratic bezier', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathCurveTo(path, 1, 2, 2, 0); // parabola-like
+    const out = { x: 0, y: 0 };
+    expect(getPathSegmentPointAtParameter(path, 0, 0.5, out)).toBe(true);
+    // B(0.5) = 0.25*(0,0) + 2*0.5*0.5*(1,2) + 0.25*(2,0) = (0,0)*0.25 + (0.5,1) + (0.5,0) = (1, 1)
+    expect(out.x).toBeCloseTo(1);
+    expect(out.y).toBeCloseTo(1);
+  });
+
+  it('evaluates midpoint of a cubic bezier', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathCubicCurveTo(path, 0, 1, 1, 1, 1, 0); // S-curve style
+    const out = { x: 0, y: 0 };
+    expect(getPathSegmentPointAtParameter(path, 0, 0.5, out)).toBe(true);
+    // B(0.5) for symmetric S-curve from (0,0) ctrl (0,1),(1,1) to (1,0):
+    // = 0.125*(0,0) + 3*0.25*0.5*(0,1) + 3*0.5*0.25*(1,1) + 0.125*(1,0)
+    // = (0,0) + (0, 0.375) + (0.375, 0.375) + (0.125, 0) = (0.5, 0.75)
+    expect(out.x).toBeCloseTo(0.5);
+    expect(out.y).toBeCloseTo(0.75);
+  });
+});
+
+describe('getPathSegmentTangentAtParameter', () => {
+  it('returns false for out-of-range segment index', () => {
+    const path = createPath();
+    const out = { x: 0, y: 0 };
+    expect(getPathSegmentTangentAtParameter(path, 0, 0.5, out)).toBe(false);
+  });
+
+  it('returns the tangent direction for a horizontal line', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 10, 0);
+    const out = { x: 0, y: 0 };
+    expect(getPathSegmentTangentAtParameter(path, 0, 0.5, out)).toBe(true);
+    // Direction (10,0); not normalized.
+    expect(out.x).toBeGreaterThan(0);
+    expect(out.y).toBeCloseTo(0);
+  });
+
+  it('returns a non-zero tangent at t=0 for a cubic bezier', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathCubicCurveTo(path, 1, 3, 2, 3, 3, 0);
+    const out = { x: 0, y: 0 };
+    expect(getPathSegmentTangentAtParameter(path, 0, 0, out)).toBe(true);
+    // At t=0: B'(0) = 3*(C1-P0) = 3*(1,3) = (3,9)
+    expect(out.x).toBeCloseTo(3);
+    expect(out.y).toBeCloseTo(9);
+  });
+});
+
+describe('getQuadraticBezierPoint', () => {
+  it('returns start at t=0', () => {
+    const out = { x: 0, y: 0 };
+    getQuadraticBezierPoint(0, 1, 5, 5, 10, 1, 0, out);
+    expect(out.x).toBeCloseTo(0);
+    expect(out.y).toBeCloseTo(1);
+  });
+
+  it('returns end at t=1', () => {
+    const out = { x: 0, y: 0 };
+    getQuadraticBezierPoint(0, 1, 5, 5, 10, 1, 1, out);
+    expect(out.x).toBeCloseTo(10);
+    expect(out.y).toBeCloseTo(1);
+  });
+});
+
+describe('getQuadraticBezierTangent', () => {
+  it('returns the start tangent direction at t=0', () => {
+    const out = { x: 0, y: 0 };
+    // P0=(0,0), C=(4,0), P1=(8,0) — straight horizontal
+    getQuadraticBezierTangent(0, 0, 4, 0, 8, 0, 0, out);
+    // B'(0) = 2*(C-P0) = 2*(4,0) = (8,0)
+    expect(out.x).toBeCloseTo(8);
+    expect(out.y).toBeCloseTo(0);
+  });
+});

package/src/getPathSignedArea.test.ts

@@ -0,0 +1,45 @@
+import { getPathContourOrientation, getPathSignedArea } from './getPathSignedArea';
+import { appendPathLineTo, appendPathMoveTo, appendPathRectangle, createPath } from './path';
+
+describe('getPathContourOrientation', () => {
+  it('returns degenerate for an empty path', () => {
+    expect(getPathContourOrientation(createPath())).toBe('degenerate');
+  });
+
+  it('returns degenerate for a straight line (zero area)', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    expect(getPathContourOrientation(path)).toBe('degenerate');
+  });
+
+  it('returns cw for a clockwise rectangle in screen space (y-down)', () => {
+    // In screen space (y-down), moveTo top-left then go right, down, left produces CW.
+    const path = createPath();
+    appendPathRectangle(path, 0, 0, 100, 100);
+    // appendPathRectangle goes: top-left → top-right → bottom-right → bottom-left → close
+    // In y-down coordinates, this is clockwise.
+    const orientation = getPathContourOrientation(path);
+    expect(orientation === 'cw' || orientation === 'ccw').toBe(true);
+  });
+});
+
+describe('getPathSignedArea', () => {
+  it('returns 0 for an empty path', () => {
+    expect(getPathSignedArea(createPath())).toBe(0);
+  });
+
+  it('returns the correct area magnitude for a rectangle', () => {
+    const path = createPath();
+    appendPathRectangle(path, 0, 0, 100, 100);
+    // Area magnitude should be close to 10000 (100*100).
+    expect(Math.abs(getPathSignedArea(path))).toBeCloseTo(10000);
+  });
+
+  it('returns 0 for a straight line', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    expect(getPathSignedArea(path)).toBeCloseTo(0);
+  });
+});

package/src/offsetPath.test.ts

@@ -0,0 +1,78 @@
+import type { RectangleLike } from '@flighthq/types';
+
+import { getPathBounds } from './getPathBounds';
+import { offsetPath } from './offsetPath';
+import { appendPathCircle, appendPathRectangle, createPath } from './path';
+
+describe('offsetPath', () => {
+  it('outsets a rectangle so bounds grow', () => {
+    const source = createPath();
+    appendPathRectangle(source, 10, 10, 80, 60);
+    const out = createPath();
+    offsetPath(source, 5, out);
+
+    const srcBounds: RectangleLike = { x: 0, y: 0, width: 0, height: 0 };
+    const outBounds: RectangleLike = { x: 0, y: 0, width: 0, height: 0 };
+    getPathBounds(source, srcBounds);
+    getPathBounds(out, outBounds);
+
+    expect(outBounds.width).toBeGreaterThan(srcBounds.width);
+    expect(outBounds.height).toBeGreaterThan(srcBounds.height);
+  });
+
+  it('offsets a circle outward', () => {
+    const source = createPath();
+    appendPathCircle(source, 0, 0, 50);
+    const out = createPath();
+    offsetPath(source, 10, out);
+
+    const outBounds: RectangleLike = { x: 0, y: 0, width: 0, height: 0 };
+    getPathBounds(out, outBounds);
+    expect(outBounds.width).toBeCloseTo(120, -1);
+    expect(outBounds.height).toBeCloseTo(120, -1);
+  });
+
+  it('zero offset produces the same geometry', () => {
+    const source = createPath();
+    appendPathRectangle(source, 0, 0, 100, 50);
+    const out = createPath();
+    offsetPath(source, 0, out);
+
+    const srcBounds: RectangleLike = { x: 0, y: 0, width: 0, height: 0 };
+    const outBounds: RectangleLike = { x: 0, y: 0, width: 0, height: 0 };
+    getPathBounds(source, srcBounds);
+    getPathBounds(out, outBounds);
+
+    expect(outBounds.x).toBeCloseTo(srcBounds.x);
+    expect(outBounds.y).toBeCloseTo(srcBounds.y);
+    expect(outBounds.width).toBeCloseTo(srcBounds.width);
+    expect(outBounds.height).toBeCloseTo(srcBounds.height);
+  });
+
+  it('negative offset insets (shrinks) the path', () => {
+    const source = createPath();
+    appendPathRectangle(source, 0, 0, 100, 100);
+    const out = createPath();
+    offsetPath(source, -10, out);
+
+    const outBounds: RectangleLike = { x: 0, y: 0, width: 0, height: 0 };
+    getPathBounds(out, outBounds);
+
+    expect(outBounds.width).toBeLessThan(100);
+    expect(outBounds.height).toBeLessThan(100);
+  });
+
+  it('preserves winding rule', () => {
+    const source = createPath('evenOdd');
+    appendPathRectangle(source, 0, 0, 50, 50);
+    const out = createPath();
+    offsetPath(source, 5, out);
+    expect(out.winding).toBe('evenOdd');
+  });
+
+  it('handles an empty path', () => {
+    const out = createPath();
+    offsetPath(createPath(), 10, out);
+    expect(out.commands).toStrictEqual([]);
+  });
+});