@flighthq/path 0.1.0

package/src/strokePath.test.ts

@@ -0,0 +1,150 @@
+import { PathCommand } from '@flighthq/types';
+
+import { appendPathClose, appendPathLineTo, appendPathMoveTo, createPath } from './path';
+import { strokePath } from './strokePath';
+
+describe('strokePath', () => {
+  it('returns an empty path for an empty input', () => {
+    const result = strokePath(createPath(), {});
+    expect(result.commands.length).toBe(0);
+  });
+
+  it('returns a closed outline for a horizontal line (butt caps)', () => {
+    // A horizontal line from (0,0) to (100,0) with width 10 and butt caps should produce
+    // a closed rectangular outline.
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    const result = strokePath(path, { width: 10, cap: 'butt' });
+    // The result must contain at least one CLOSE
+    expect(result.commands).toContain(PathCommand.CLOSE);
+    // And at least one MOVE_TO
+    expect(result.commands).toContain(PathCommand.MOVE_TO);
+    // Width=10, so offset = 5. y values should be near ±5.
+    const yValues = result.data.filter((_, i) => i % 2 === 1);
+    expect(Math.max(...yValues)).toBeCloseTo(5);
+    expect(Math.min(...yValues)).toBeCloseTo(-5);
+  });
+
+  it('extends endpoints for square caps', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    const result = strokePath(path, { width: 10, cap: 'square' });
+    // Square caps extend by halfWidth (5) on each end. x range should be [-5, 105].
+    const xValues = result.data.filter((_, i) => i % 2 === 0);
+    expect(Math.min(...xValues)).toBeCloseTo(-5);
+    expect(Math.max(...xValues)).toBeCloseTo(105);
+  });
+
+  it('produces round caps with extra points for a curved endcap', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    const buttResult = strokePath(path, { width: 10, cap: 'butt' });
+    const roundResult = strokePath(path, { width: 10, cap: 'round' });
+    // Round caps produce more outline points than butt caps.
+    expect(roundResult.commands.length).toBeGreaterThan(buttResult.commands.length);
+  });
+
+  it('handles a closed path without adding caps', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    appendPathLineTo(path, 100, 100);
+    appendPathClose(path);
+    const result = strokePath(path, { width: 4 });
+    // Closed path produces at least one closed contour.
+    expect(result.commands).toContain(PathCommand.CLOSE);
+  });
+
+  it('produces fewer outline points with a coarser tolerance', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    const fine = strokePath(path, { width: 10, cap: 'round' }, 0.1).commands.length;
+    const coarse = strokePath(path, { width: 10, cap: 'round' }, 10).commands.length;
+    expect(coarse).toBeLessThanOrEqual(fine);
+  });
+
+  // Dashing edge cases.
+  it('dashes: produces multiple segments for a simple on/off pattern', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    // dash=[10,10]: alternating 10-unit on, 10-unit off
+    const result = strokePath(path, { width: 2, dash: [10, 10] });
+    // Should produce at least 2 closed outlines (multiple MOVE_TO).
+    const moveTos = result.commands.filter((c) => c === PathCommand.MOVE_TO).length;
+    expect(moveTos).toBeGreaterThanOrEqual(2);
+  });
+
+  it('dashes: dashOffset shifts the pattern start position', () => {
+    // Path of 25 units. dash=[20, 5] = on for 20, off for 5.
+    // dashOffset=0: on 0-20, off 20-25 → 1 dash.
+    // dashOffset=15: we are 15 units into the dash at start. remaining on = 5.
+    //   on 0-5, off 5-10, on 10-25 → 2 dashes.
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 25, 0);
+    const result0 = strokePath(path, { width: 2, dash: [20, 5], dashOffset: 0 });
+    const result15 = strokePath(path, { width: 2, dash: [20, 5], dashOffset: 15 });
+    const moveTos0 = result0.commands.filter((c) => c === PathCommand.MOVE_TO).length;
+    const moveTos15 = result15.commands.filter((c) => c === PathCommand.MOVE_TO).length;
+    expect(moveTos0).toBe(1);
+    expect(moveTos15).toBe(2);
+  });
+
+  it('dashes: zero-length dash entry is ignored (no infinite loop)', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    // A zero-length dash entry should not cause an infinite loop or throw.
+    expect(() => strokePath(path, { width: 2, dash: [0, 10, 10, 10] })).not.toThrow();
+  });
+
+  it('dashes: very short segments produce the correct number of dashes', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    // Total path length = 5 (very short relative to the 10-unit dash)
+    appendPathLineTo(path, 5, 0);
+    const result = strokePath(path, { width: 1, dash: [10, 10] });
+    // Only one dash segment should appear since the whole path < first dash length.
+    const moveTos = result.commands.filter((c) => c === PathCommand.MOVE_TO).length;
+    expect(moveTos).toBe(1);
+  });
+
+  it('dashes: pattern wraps correctly across multiple path segments', () => {
+    // Two segments of 25 each = 50 total, with dash=[15,5]: wraps at 20/40 so has 2+ dashes.
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 25, 0);
+    appendPathLineTo(path, 50, 0);
+    const result = strokePath(path, { width: 1, dash: [15, 5] });
+    const moveTos = result.commands.filter((c) => c === PathCommand.MOVE_TO).length;
+    // dash=[15,5]: on 0-15, off 15-20, on 20-35, off 35-40, on 40-50 → 3 dashes
+    expect(moveTos).toBeGreaterThanOrEqual(2);
+  });
+
+  it('dashes: solid stroke (empty dash array) produces a single outline', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    const solid = strokePath(path, { width: 4, dash: [] });
+    const moveTos = solid.commands.filter((c) => c === PathCommand.MOVE_TO).length;
+    expect(moveTos).toBe(1);
+  });
+
+  it('dashes: multiple subpaths each get the dash pattern applied independently', () => {
+    // Two separate subpaths each of length 100; dash=[30,10] gives 3 dashes per subpath.
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    appendPathMoveTo(path, 0, 20);
+    appendPathLineTo(path, 100, 20);
+    const result = strokePath(path, { width: 2, dash: [30, 10] });
+    const moveTos = result.commands.filter((c) => c === PathCommand.MOVE_TO).length;
+    // At least 2 subpaths × at least 1 dash each.
+    expect(moveTos).toBeGreaterThanOrEqual(2);
+  });
+});

package/src/tessellatePath.test.ts

@@ -0,0 +1,62 @@
+import type { PathMesh } from '@flighthq/types';
+
+import { appendPathLineTo, appendPathMoveTo, createPath } from './path';
+import { tessellatePath } from './tessellatePath';
+
+function meshArea(mesh: PathMesh): number {
+  let area = 0;
+  for (let i = 0; i < mesh.indices.length; i += 3) {
+    const i0 = mesh.indices[i];
+    const i1 = mesh.indices[i + 1];
+    const i2 = mesh.indices[i + 2];
+    const ax = mesh.vertices[i0 * 2];
+    const ay = mesh.vertices[i0 * 2 + 1];
+    const bx = mesh.vertices[i1 * 2];
+    const by = mesh.vertices[i1 * 2 + 1];
+    const cx = mesh.vertices[i2 * 2];
+    const cy = mesh.vertices[i2 * 2 + 1];
+    area += Math.abs((bx - ax) * (cy - ay) - (cx - ax) * (by - ay)) / 2;
+  }
+  return area;
+}
+
+function polygon(...points: number[]): ReturnType<typeof createPath> {
+  const path = createPath();
+  appendPathMoveTo(path, points[0], points[1]);
+  for (let i = 2; i < points.length; i += 2) {
+    appendPathLineTo(path, points[i], points[i + 1]);
+  }
+  return path;
+}
+
+describe('tessellatePath', () => {
+  it('triangulates a triangle into one triangle', () => {
+    const mesh = tessellatePath(polygon(0, 0, 10, 0, 0, 10));
+    expect(mesh.indices).toHaveLength(3);
+    expect(meshArea(mesh)).toBeCloseTo(50);
+  });
+
+  it('triangulates a square into two triangles covering its area', () => {
+    const mesh = tessellatePath(polygon(0, 0, 10, 0, 10, 10, 0, 10));
+    expect(mesh.indices).toHaveLength(6);
+    expect(meshArea(mesh)).toBeCloseTo(100);
+  });
+
+  it('triangulates a concave L-shape conserving area (n-2 triangles)', () => {
+    const mesh = tessellatePath(polygon(0, 0, 20, 0, 20, 10, 10, 10, 10, 20, 0, 20));
+    expect(mesh.indices).toHaveLength(12); // 6 vertices → 4 triangles
+    expect(meshArea(mesh)).toBeCloseTo(300);
+  });
+
+  it('drops a trailing point that closes the contour explicitly', () => {
+    const mesh = tessellatePath(polygon(0, 0, 10, 0, 10, 10, 0, 10, 0, 0));
+    expect(mesh.vertices).toHaveLength(8); // 4 unique vertices, not 5
+    expect(meshArea(mesh)).toBeCloseTo(100);
+  });
+
+  it('produces an empty mesh for a degenerate contour', () => {
+    const mesh = tessellatePath(polygon(0, 0, 10, 0));
+    expect(mesh.indices).toHaveLength(0);
+    expect(mesh.vertices).toHaveLength(0);
+  });
+});

package/src/tessellatePathTyped.test.ts

@@ -0,0 +1,26 @@
+import { appendPathRectangle, createPath } from './path';
+import { tessellatePath } from './tessellatePath';
+import { tessellatePathTyped } from './tessellatePathTyped';
+
+describe('tessellatePathTyped', () => {
+  it('returns Float32Array vertices and Uint32Array indices', () => {
+    const path = createPath();
+    appendPathRectangle(path, 0, 0, 100, 100);
+    const mesh = tessellatePathTyped(path);
+    expect(mesh.vertices).toBeInstanceOf(Float32Array);
+    expect(mesh.indices).toBeInstanceOf(Uint32Array);
+  });
+  it('produces the same values as tessellatePath', () => {
+    const path = createPath();
+    appendPathRectangle(path, 10, 20, 80, 60);
+    const typed = tessellatePathTyped(path);
+    const plain = tessellatePath(path);
+    expect(Array.from(typed.vertices)).toStrictEqual(plain.vertices);
+    expect(Array.from(typed.indices)).toStrictEqual(plain.indices);
+  });
+  it('returns empty typed arrays for an empty path', () => {
+    const mesh = tessellatePathTyped(createPath());
+    expect(mesh.vertices.length).toBe(0);
+    expect(mesh.indices.length).toBe(0);
+  });
+});

package/src/transformPath.test.ts

@@ -0,0 +1,79 @@
+import { appendPathCubicCurveTo, appendPathCurveTo, appendPathLineTo, appendPathMoveTo, createPath } from './path';
+import { transformPath, translatePath } from './transformPath';
+
+const IDENTITY = { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 };
+
+describe('transformPath', () => {
+  it('identity matrix leaves all coordinates unchanged', () => {
+    const source = createPath();
+    appendPathMoveTo(source, 10, 20);
+    appendPathLineTo(source, 30, 40);
+    const out = createPath();
+    transformPath(source, IDENTITY, out);
+    expect(out.data).toStrictEqual([10, 20, 30, 40]);
+  });
+
+  it('applies a translation to MOVE_TO and LINE_TO points', () => {
+    const source = createPath();
+    appendPathMoveTo(source, 0, 0);
+    appendPathLineTo(source, 10, 0);
+    const out = createPath();
+    transformPath(source, { a: 1, b: 0, c: 0, d: 1, tx: 5, ty: 3 }, out);
+    expect(out.data).toStrictEqual([5, 3, 15, 3]);
+  });
+
+  it('applies a scale to CURVE_TO control and anchor points', () => {
+    const source = createPath();
+    appendPathMoveTo(source, 0, 0);
+    appendPathCurveTo(source, 10, 20, 30, 0);
+    const out = createPath();
+    transformPath(source, { a: 2, b: 0, c: 0, d: 2, tx: 0, ty: 0 }, out);
+    // MOVE_TO (0,0) scaled to (0,0); CURVE_TO (10,20,30,0) → (20,40,60,0)
+    expect(out.data).toStrictEqual([0, 0, 20, 40, 60, 0]);
+  });
+
+  it('applies a scale to CUBIC_CURVE_TO points', () => {
+    const source = createPath();
+    appendPathMoveTo(source, 0, 0);
+    appendPathCubicCurveTo(source, 10, 0, 20, 0, 30, 0);
+    const out = createPath();
+    transformPath(source, { a: 3, b: 0, c: 0, d: 3, tx: 0, ty: 0 }, out);
+    expect(out.data).toStrictEqual([0, 0, 30, 0, 60, 0, 90, 0]);
+  });
+
+  it('is alias-safe: out may be the same object as source', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 5, 10);
+    appendPathLineTo(path, 15, 20);
+    transformPath(path, { a: 1, b: 0, c: 0, d: 1, tx: 100, ty: 200 }, path);
+    expect(path.data).toStrictEqual([105, 210, 115, 220]);
+  });
+
+  it('copies winding and commands from source to out', () => {
+    const source = createPath('evenOdd');
+    appendPathMoveTo(source, 0, 0);
+    appendPathLineTo(source, 1, 1);
+    const out = createPath('nonZero');
+    transformPath(source, IDENTITY, out);
+    expect(out.winding).toBe('evenOdd');
+    expect(out.commands).toStrictEqual(source.commands);
+  });
+});
+
+describe('translatePath', () => {
+  it('shifts all points by (dx, dy)', () => {
+    const source = createPath();
+    appendPathMoveTo(source, 0, 0);
+    appendPathLineTo(source, 10, 10);
+    const out = createPath();
+    translatePath(source, 5, -3, out);
+    expect(out.data).toStrictEqual([5, -3, 15, 7]);
+  });
+
+  it('is alias-safe', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 1, 2);
+    translatePath(path, 10, 20, path);
+    expect(path.data).toStrictEqual([11, 22]);
+  });
+});