feat(zoom): implement focal point zooming without matrices

timmywil · Jul 27, 2019 · 5d077f1 · 5d077f1
1 parent ee6c5bb
commit 5d077f1
Show file tree

Hide file tree

Showing 21 changed files with 646 additions and 799 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -98,5 +98,5 @@ Here are the npm scripts that run tests:
 ```bash
 $ yarn test # Lints and runs the unit tests
 $ yarn test:unit # Runs the unit tests
-$ yarn test:unit:watch # Watches files and runs the unit tests on file save
+$ yarn test:watch # Watches files and runs the unit tests on file save
 ```
diff --git a/docs/README.md b/docs/README.md
@@ -1,53 +1,52 @@
+> **[panzoom](README.md)**
 
-Panzoom
-=======
+[Globals](globals.md) /
+
+# Panzoom
 
 [![Build Status](https://travis-ci.org/timmywil/panzoom.png?branch=master)](https://travis-ci.org/timmywil/panzoom)
 
 **[Documentation](./docs/)**
 
 **[Examples](https://timmywil.com/panzoom/test/demo/)**
 
-Panzoom is a small library to add panning and zooming functionality to an element. Rather than setting width and height, Panzoom uses CSS transforms and matrix functions to take advantage of hardware/GPU acceleration in the browser, which means the element can be _anything_: an image, a video, an iframe, a canvas, text, WHATEVER.
+Panzoom is a small library to add panning and zooming functionality to an element.
+Rather than setting width and height, Panzoom uses CSS transforms and matrix functions to take advantage of hardware/GPU acceleration in the browser, which means the element can be _anything_: an image, a video, an iframe, a canvas, text, WHATEVER.
 
 panzoom.min.js (12.5kb/4.6kb gzip), included in this repo, is compressed with [uglifyjs](https://github.com/mishoo/UglifyJS).
 
 For common support questions, see [the FAQ](https://github.com/timmywil/panzoom#faq) at the bottom.
 
-Dependencies
-------------
+## Dependencies
 
 Panzoom used to rely on jQuery, but is now a standalone library. However, it can still be used as a jQuery plugin.
 
-Browser support
----------------
+## Browser support
 
 Here is a list of [currently supported browsers](https://browserl.ist/?q=%3E0.25%25%2C+not+op_mini+all).
 
-Mobile support
---------------
+## Mobile support
 
 Panzoom includes support for touch gestures and even supports **pinch gestures** for zooming. It is perfectly suited for both mobile and desktop browsers.
 
 iOS and Android are supported.
 
 **Pointer**, **touch**, and **mouse** events are supported.
 
-SVG support
------------
+## SVG support
 
 Panzoom supports panning and zooming SVG elements directly, in browsers that support SVG.
 
 In IE11, CSS animations/transitions do not work on SVG elements, at least for the transform style. They do work in other browsers.
 
 One could implement transitions manually in those browsers by overriding the `setTransform()` method and integrating a tweening library for javascript animations (such as [tween.js](http://www.createjs.com/#!/TweenJS)).
 
-**Compatibility note:** _There is a \[known issue with Firefox\]([https://bugzilla.mozilla.org/show](https://bugzilla.mozilla.org/show)_bug.cgi?id=530985) and using the `focal` option. Firefox does not correctly maintain the dimensions of SVG parent elements, which throws off offsets. If using the `focal` option with SVG, the workaround is to set the correct offset on the Panzoom instance manually using `Panzoom.prototype.parentOffset` ([example](http://jsfiddle.net/timmywil/Vu8nA/)).\_
+**Compatibility note:** _There is a [known issue with Firefox](https://bugzilla.mozilla.org/show_bug.cgi?id=530985) and using the `focal` option. Firefox does not correctly maintain the dimensions of SVG parent elements, which throws off offsets. If using the `focal` option with SVG, the workaround is to set the correct offset on the Panzoom instance manually using `Panzoom.prototype.parentOffset` ([example](http://jsfiddle.net/timmywil/Vu8nA/))._
 
-Loading Panzoom
----------------
+## Loading Panzoom
 
-Panzoom can be included with your scripts at the end of the body, but Panzoom supports AMD for javascript module love.
+Panzoom can be included with your scripts at the end of the body,
+but Panzoom supports AMD for javascript module love.
 
 With script tags:
 
@@ -63,21 +62,19 @@ define(['panzoom'], function(Panzoom) {
 })
 ```
 
-Initialization
---------------
+## Initialization
 
 ```js
 const panzoom = Panzoom('.panzoom', {
   maxScale: 5
 })
 ```
 
-FAQ
----
+## FAQ
 
 1\. How do I make it so that I never see the background behind the Panzoom element? [example](http://codepen.io/timmywil/pen/qjvBF)
 
-*   This can be done with the `contain` option. Set `contain` to `"invert"` or `"auto"` and make sure the Panzoom element is the same size or larger than its parent.
+- This can be done with the `contain` option. Set `contain` to `"invert"` or `"auto"` and make sure the Panzoom element is the same size or larger than its parent.
 
 ```js
 $('.panzoom-elements').panzoom({
@@ -88,23 +85,23 @@ $('.panzoom-elements').panzoom({
 
 2\. How do I make links work if they're within a Panzoom element? [example](http://codepen.io/timmywil/pen/bFiqy)
 
-*   Event propagation is stopped for `mousedown` and `touchstart` events in order to allow for Panzoom elements within Panzoom elements. To fix the links, bind an event handler that prevents the event from reaching the Panzoom handler:
+- Event propagation is stopped for `mousedown` and `touchstart` events in order to allow for Panzoom elements within Panzoom elements. To fix the links, bind an event handler that prevents the event from reaching the Panzoom handler:
 
 ```js
 $('.panzoom a').on('mousedown touchstart', function(e) {
   e.stopImmediatePropagation()
 })
 ```
 
-3\. What is `transform-origin` and why is it added to the panzoom element
+3\. What is `transform-origin` and why is it added to the panzoom element?
 
-*   The `transform-origin` is the origin from which transforms are applied. Panzoom ensures the defaults are set to what it expects to calculate focal points and containment. The defaults are needed because certain browsers (_IE_) don't support changing them for certain elements.
-*   HTML elements default to '50% 50%'.
-*   SVG elements default to '0 0'.
+- The `transform-origin` is the origin from which transforms are applied. Panzoom ensures the defaults are set to what it expects to calculate focal points and containment. The defaults are needed because certain browsers (_IE_) don't support changing them for certain elements.
+- HTML elements default to '50% 50%'.
+- SVG elements default to '0 0'.
 
-4\. How do I prevent zooming beyond the image's original size
+4\. How do I prevent zooming beyond the image's original size?
 
-*   The `maxScale` option can be set using the image's `naturalWidth` divided by the `clientWidth`:
+- The `maxScale` option can be set using the image's `naturalWidth` divided by the `clientWidth`:
 
 ```js
 $('#large-image').panzoom({
@@ -114,16 +111,4 @@ $('#large-image').panzoom({
 
 5\. I am using Panzoom with an `<object>` tag. It zooms but does not pan. [example](http://codepen.io/timmywil/pen/qNpykA)
 
-Object elements can eat up events, making it so they never reach Panzoom. To fix this, disable pointer events on the object tag and call Panzoom using a wrapper.
-
-## Index
-
-### External modules
-
-* ["css"](modules/_css_.md)
-* ["isAttached"](modules/_isattached_.md)
-* ["isSVGElement"](modules/_issvgelement_.md)
-* ["panzoom"](modules/_panzoom_.md)
-
----
-
+Object elements can eat up events, making it so they never reach Panzoom. To fix this, disable pointer events on the object tag and call Panzoom using a wrapper.
diff --git a/docs/globals.md b/docs/globals.md
@@ -0,0 +1,14 @@
+> **[panzoom](README.md)**
+
+[Globals](globals.md) /
+
+# panzoom
+
+## Index
+
+### External modules
+
+* ["css"](modules/_css_.md)
+* ["isAttached"](modules/_isattached_.md)
+* ["isSVGElement"](modules/_issvgelement_.md)
+* ["panzoom"](modules/_panzoom_.md)
diff --git a/docs/interfaces/_panzoom_.panoptions.md b/docs/interfaces/_panzoom_.panoptions.md
@@ -1,54 +1,47 @@
-[panzoom](../README.md) > ["panzoom"](../modules/_panzoom_.md) > [PanOptions](../interfaces/_panzoom_.panoptions.md)
+> **[panzoom](../README.md)**
+
+[Globals](../globals.md) / ["panzoom"](../modules/_panzoom_.md) / [PanOptions](_panzoom_.panoptions.md) /
 
 # Interface: PanOptions
 
 ## Hierarchy
 
-**PanOptions**
+* **PanOptions**
 
 ## Index
 
 ### Properties
 
-* [cursor](_panzoom_.panoptions.md#cursor)
-* [disablePan](_panzoom_.panoptions.md#disablepan)
-* [relative](_panzoom_.panoptions.md#relative)
-
----
+* [cursor](_panzoom_.panoptions.md#optional-cursor)
+* [disablePan](_panzoom_.panoptions.md#optional-disablepan)
+* [relative](_panzoom_.panoptions.md#optional-relative)
 
 ## Properties
 
-<a id="cursor"></a>
-
-### `<Optional>` cursor
+### `Optional` cursor
 
-**● cursor**: *`string`*
+• **cursor**? : *string*
 
-*Defined in [panzoom.ts:20](https://github.com/timmywil/panzoom/blob/ea9f617/src/panzoom.ts#L20)*
+*Defined in [panzoom.ts:20](https://github.com/timmywil/panzoom/blob/45fed7d/src/panzoom.ts#L20)*
 
 The cursor style to set on the panzoom element
 
 ___
-<a id="disablepan"></a>
 
-### `<Optional>` disablePan
+### `Optional` disablePan
 
-**● disablePan**: *`boolean`*
+• **disablePan**? : *boolean*
 
-*Defined in [panzoom.ts:16](https://github.com/timmywil/panzoom/blob/ea9f617/src/panzoom.ts#L16)*
+*Defined in [panzoom.ts:16](https://github.com/timmywil/panzoom/blob/45fed7d/src/panzoom.ts#L16)*
 
 Disable panning functionality. Note: disablePan also disables focal point zooming
 
 ___
-<a id="relative"></a>
 
-### `<Optional>` relative
+### `Optional` relative
 
-**● relative**: *`boolean`*
+• **relative**? : *boolean*
 
-*Defined in [panzoom.ts:18](https://github.com/timmywil/panzoom/blob/ea9f617/src/panzoom.ts#L18)*
-
-When passing x and y values to .pan(), treat the values as relative to their current values
-
-___
+*Defined in [panzoom.ts:18](https://github.com/timmywil/panzoom/blob/45fed7d/src/panzoom.ts#L18)*
 
+When passing x and y values to .pan(), treat the values as relative to their current values
diff --git a/docs/interfaces/_panzoom_.panzoominstance.md b/docs/interfaces/_panzoom_.panzoominstance.md
@@ -1,10 +1,12 @@
-[panzoom](../README.md) > ["panzoom"](../modules/_panzoom_.md) > [PanzoomInstance](../interfaces/_panzoom_.panzoominstance.md)
+> **[panzoom](../README.md)**
+
+[Globals](../globals.md) / ["panzoom"](../modules/_panzoom_.md) / [PanzoomInstance](_panzoom_.panzoominstance.md) /
 
 # Interface: PanzoomInstance
 
 ## Hierarchy
 
-**PanzoomInstance**
+* **PanzoomInstance**
 
 ## Index
 
@@ -15,28 +17,23 @@
 * [zoom](_panzoom_.panzoominstance.md#zoom)
 * [zoomWithWheel](_panzoom_.panzoominstance.md#zoomwithwheel)
 
----
-
 ## Properties
 
-<a id="options"></a>
-
 ###  options
 
-**● options**: *[PanzoomOptions](../modules/_panzoom_.md#panzoomoptions)*
+• **options**: *[PanzoomOptions](../modules/_panzoom_.md#panzoomoptions)*
 
-*Defined in [panzoom.ts:89](https://github.com/timmywil/panzoom/blob/ea9f617/src/panzoom.ts#L89)*
+*Defined in [panzoom.ts:89](https://github.com/timmywil/panzoom/blob/45fed7d/src/panzoom.ts#L89)*
 
 The contructed options for this Panzoom instance
 
 ___
-<a id="pan"></a>
 
 ###  pan
 
-**● pan**: *`function`*
+• **pan**: *function*
 
-*Defined in [panzoom.ts:67](https://github.com/timmywil/panzoom/blob/ea9f617/src/panzoom.ts#L67)*
+*Defined in [panzoom.ts:67](https://github.com/timmywil/panzoom/blob/45fed7d/src/panzoom.ts#L67)*
 
 Pan the Panzoom element to the given x and y coordinates
 
@@ -47,27 +44,25 @@ panzoom.pan(50, 100)
 panzoom.pan(10, 10, { relative: true })
 ```
 
-#### Type declaration
-▸(x: *`number` \| `string`*, y: *`number` \| `string`*, panOptions?: *[PanOptions](_panzoom_.panoptions.md)*): `void`
+#### Type declaration:
 
-**Parameters:**
+▸ (`x`: number | string, `y`: number | string, `panOptions?`: [PanOptions](_panzoom_.panoptions.md)): *void*
 
-| Name | Type |
-| ------ | ------ |
-| x | `number` \| `string` |
-| y | `number` \| `string` |
-| `Optional` panOptions | [PanOptions](_panzoom_.panoptions.md) |
+**Parameters:**
 
-**Returns:** `void`
+Name | Type |
+------ | ------ |
+`x` | number \| string |
+`y` | number \| string |
+`panOptions?` | [PanOptions](_panzoom_.panoptions.md) |
 
 ___
-<a id="zoom"></a>
 
 ###  zoom
 
-**● zoom**: *`function`*
+• **zoom**: *function*
 
-*Defined in [panzoom.ts:76](https://github.com/timmywil/panzoom/blob/ea9f617/src/panzoom.ts#L76)*
+*Defined in [panzoom.ts:76](https://github.com/timmywil/panzoom/blob/45fed7d/src/panzoom.ts#L76)*
 
 Zoom the Panzoom element to the given scale
 
@@ -76,26 +71,24 @@ panzoom.zoom(2.2)
 panzoom.zoom(2.2, { animate: true })
 ```
 
-#### Type declaration
-▸(scale: *`number`*, zoomOptions?: *[ZoomOptions](_panzoom_.zoomoptions.md)*): `void`
+#### Type declaration:
 
-**Parameters:**
+▸ (`scale`: number, `zoomOptions?`: [ZoomOptions](_panzoom_.zoomoptions.md)): *void*
 
-| Name | Type |
-| ------ | ------ |
-| scale | `number` |
-| `Optional` zoomOptions | [ZoomOptions](_panzoom_.zoomoptions.md) |
+**Parameters:**
 
-**Returns:** `void`
+Name | Type |
+------ | ------ |
+`scale` | number |
+`zoomOptions?` | [ZoomOptions](_panzoom_.zoomoptions.md) |
 
 ___
-<a id="zoomwithwheel"></a>
 
 ###  zoomWithWheel
 
-**● zoomWithWheel**: *`function`*
+• **zoomWithWheel**: *function*
 
-*Defined in [panzoom.ts:87](https://github.com/timmywil/panzoom/blob/ea9f617/src/panzoom.ts#L87)*
+*Defined in [panzoom.ts:87](https://github.com/timmywil/panzoom/blob/45fed7d/src/panzoom.ts#L87)*
 
 Zoom the Panzoom element to a focal point using the given WheelEvent
 
@@ -106,17 +99,13 @@ elem.parentElement.addEventListener('wheel', function(event) {
 })
 ```
 
-#### Type declaration
-▸(event: *`WheelEvent`*, zoomOptions?: *[PanzoomOptions](../modules/_panzoom_.md#panzoomoptions)*): `void`
-
-**Parameters:**
-
-| Name | Type |
-| ------ | ------ |
-| event | `WheelEvent` |
-| `Optional` zoomOptions | [PanzoomOptions](../modules/_panzoom_.md#panzoomoptions) |
+#### Type declaration:
 
-**Returns:** `void`
+▸ (`event`: `WheelEvent`, `zoomOptions?`: [PanzoomOptions](../modules/_panzoom_.md#panzoomoptions)): *void*
 
-___
+**Parameters:**
 
+Name | Type |
+------ | ------ |
+`event` | `WheelEvent` |
+`zoomOptions?` | [PanzoomOptions](../modules/_panzoom_.md#panzoomoptions) |