feat(core): Added Path.combine and related changes, closes #5976

The discussion in #5976 is whether `Path.join()` should use a line
segment to close any gaps in the path caused by move operations, or by
differences in the end and start points of paths being joined.

The answer is yes, that is the intended behaviour, but people who read
_join_ might expect differently.

So I have made a few changes to clarify this:

- The new `Path.combine()` method combines multiple path instances into
  a single instance without making any changes to the drawing operations
- Since `Path.combine()` is variadic, I have also updated `Path.join()`
  to be variadic too, since that is more consistent.
- The old way of calling `Path.join(path, bool)` is deprecated and will
  log a warning. Calling `Path.join()` this way will be removed in v4.
- Related to this change is how `Path.length()` should behave when there
  are gaps in the path. Currently, it skips those. So I've added a
  parameter that when set to `true` will include them.
- Added documentation for `Path.combine()`
- Updated documentation for `Path.join()`
- Updated documentation for `Path.length()`

packages/core/tests/path.test.mjs

@@ -197,6 +197,7 @@ describe('Path', () => {
       .curve(new Point(0, 40), new Point(123, 34), new Point(230, 4))
     const joint = curve.join(line)
     expect(joint.ops.length).to.equal(4)
+    expect(joint.ops[2].type).to.equal('line')
   })
 
   it('Should join paths that have noop operations', () => {
@@ -209,7 +210,7 @@ describe('Path', () => {
     expect(joint.ops.length).to.equal(6)
   })
 
-  it('Should throw error when joining a closed paths', () => {
+  it('Should throw error when joining a closed path', () => {
     const line = new Path().move(new Point(0, 0)).line(new Point(0, 40))
     const curve = new Path()
       .move(new Point(123, 456))
@@ -218,6 +219,16 @@ describe('Path', () => {
     expect(() => curve.join(line)).to.throw()
   })
 
+  it('Should combine paths', () => {
+    const line = new Path().move(new Point(0, 0)).line(new Point(0, 40))
+    const curve = new Path()
+      .move(new Point(123, 456))
+      .curve(new Point(0, 40), new Point(123, 34), new Point(230, 4))
+    const combo = curve.combine(line)
+    expect(combo.ops.length).to.equal(4)
+    expect(combo.ops[2].type).to.equal('move')
+  })
+
   it('Should shift along a line', () => {
     const line = new Path().move(new Point(0, 0)).line(new Point(0, 40))
     expect(line.shiftAlong(20).y).to.equal(20)