refactor(dia.Paper)!: transformation events improvement

[kumilingus]

Description

The PR aim to improve the current transformation API.

• Remove outdated method:

  • origin option removed
  • setOrigin() method removed
  • rotate() (experimental) method removed

• It introduces a new transform event which is triggered after both scale and translate are finished.

• It allows passing custom data along with transformation events (similarly to mvc.Events).

  • scale(sx, sy, [data])
  • translate(tx, ty, [data])
  • matrix(matrix, [data])

paper.on('scale', (sx, sy, data) => console.log(sx, sy, data.foo));
paper.on('translate', (tx, ty, data) => console.log(tx, ty, data.foo));
paper.on('transform', (matrix, data) => console.log(matrix, data.foo));

paper.matrix({ a: 2, b: 0, c: 0, d: 2, e: 10, f: 10 }, { foo: 'bar' }); // will trigger all events

• It allows passing custom data along with the resize event

paper.on('resize', (width, height, data) => console.log(width, height, data.foo));
paper.setDimensions(100, 200, { foo: 'bar' });

• Simplify the "zooming under pointer" functionality by:
  • adding a new method scaleUniformAtPoint(scale, { x, y }, [data])
  • scale() no longer accepts scaling origin
  • fixing the original scaling at point logic (taking the previous scale into account) as per https://github.com/clientIO/joint/pull/1375

Migration guide

dia.Paper.prototype.options.origin option removed

Note that passing origin to the dia.Paper constructor had no effect in version 3.7. If you read the values of origin from the paper options, use paper.translate() (or paper.matrix()) instead.

Before:

const { x, y } = paper.option.origin;

Now:

const { tx: x, ty: y } = paper.translate();

Paper scale event handler arguments changed

Before:

paper.on('scale', (sx, sy, ox, oy) => {});

Now:

paper.on('scale', (sx, sy, data) => {
  const { tx: ox, ty: oy } = paper.translate();
});

dia.Paper.prototype.setOrigin option removed

Before:

paper.setOrigin(100, 200);

Now:

paper.translate(100, 200);

scale() no longer accepts scaling origin

Before:

// Zoom at center of the paper
const center = paper.getArea.center();
paper.translate(0,0);
paper.scale(zoomLevel, zoomLevel, center.x, center.y);

Now:

// Zoom at center of the paper
const center = paper.getArea.center();
paper.scaleUniformAtPoint(zoomLevel, center);

Paper panning and zooming can be implemented as simple as shown below:

paper.on('paper:pinch', function(evt, x, y, sx) {
    const { sx: sx0 } = paper.scale();
    paper.scaleUniformAtPoint(sx0 * sx, { x, y });
});

paper.on('paper:pan', function(evt, tx, ty) {
    evt.preventDefault();
    const { tx: tx0, ty: ty0 } = paper.translate();
    paper.translate(tx0 - tx, ty0 - ty);
});