From 5ea9c1f3ec0b14cd41a97a779b0d5d2ae1e2cdd2 Mon Sep 17 00:00:00 2001 From: Timmy Willison Date: Mon, 10 Mar 2025 15:30:54 -0400 Subject: [PATCH] fix(panzoom): ignore force when passed globally Ref gh-679 --- README.md | 133 +++++++++++++++++++------------------- src/panzoom.ts | 20 +++--- src/types.ts | 13 ++-- tasks/docs.js | 9 +-- test/unit/panzoom.test.ts | 26 ++++++++ 5 files changed, 114 insertions(+), 87 deletions(-) diff --git a/README.md b/README.md index ea6d53bc..1d860ade 100644 --- a/README.md +++ b/README.md @@ -153,7 +153,7 @@ See this [stackoverflow question](https://stackoverflow.com/questions/70428922/p > **Panzoom**(`elem`, `options`?): `[PanzoomObject](#PanzoomObject)` -Defined in: [panzoom.ts:60](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/panzoom.ts#L60) +Defined in: [panzoom.ts:60](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/panzoom.ts#L60) ## Parameters @@ -163,7 +163,7 @@ Defined in: [panzoom.ts:60](https://github.com/timmywil/panzoom/blob/c77d09dcbe5 ### options? -`[PanzoomOptionsWithoutForce](#PanzoomOptionsWithoutForce)` +`[PanzoomGlobalOptions](#PanzoomGlobalOptions)` ## Returns @@ -173,7 +173,7 @@ Defined in: [panzoom.ts:60](https://github.com/timmywil/panzoom/blob/c77d09dcbe5 Includes `MiscOptions`, `PanOptions`, and `ZoomOptions` -## `PanzoomOptionsWithoutForce` +## `PanzoomGlobalOptions` Identical to PanzoomOptions, but excludes the `force` option. @@ -181,7 +181,7 @@ Identical to PanzoomOptions, but excludes the `force` option. These options can be passed to `Panzoom()`, as well as any pan or zoom function. One exception is `force`, which can only be passed to methods like `pan()` or `zoom()`, but not `Panzoom()` or `setOptions()` as it should not be set globally. -Defined in: [types.ts:19](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L19) +Defined in: [types.ts:19](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L19) ## Indexable @@ -193,7 +193,7 @@ Defined in: [types.ts:19](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cb > `optional` **animate**: `boolean` (Default: **false**) -Defined in: [types.ts:21](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L21) +Defined in: [types.ts:21](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L21) Whether to animate transitions @@ -203,7 +203,7 @@ Whether to animate transitions > `optional` **canvas**: `boolean` (Default: **false**) -Defined in: [types.ts:32](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L32) +Defined in: [types.ts:32](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L32) This option treats the Panzoom element's parent as a canvas. Effectively, Panzoom binds the @@ -220,7 +220,7 @@ where the `cursor` style is applied (i.e. the parent). > `optional` **duration**: `number` (Default: **200**) -Defined in: [types.ts:34](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L34) +Defined in: [types.ts:34](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L34) Duration of the transition (ms) @@ -230,7 +230,7 @@ Duration of the transition (ms) > `optional` **easing**: `string` (Default: **"ease-in-out"**) -Defined in: [types.ts:36](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L36) +Defined in: [types.ts:36](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L36) CSS Easing used for transitions @@ -240,7 +240,7 @@ CSS Easing used for transitions > `optional` **exclude**: `Element`[] (Default: **[]**) -Defined in: [types.ts:43](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L43) +Defined in: [types.ts:43](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L43) Add elements to this array that should be excluded from Panzoom handling. @@ -253,7 +253,7 @@ e.g. links and buttons that should not propagate the click event. > `optional` **excludeClass**: `string` (Default: **"panzoom-exclude"**) -Defined in: [types.ts:50](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L50) +Defined in: [types.ts:50](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L50) Add this class to any element within the Panzoom element that you want to exclude from Panzoom handling. That @@ -266,14 +266,15 @@ e.g. links and buttons that should not propagate the click event. > `optional` **force**: `boolean` -Defined in: [types.ts:66](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L66) +Defined in: [types.ts:67](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L67) + +The `force` option can only be passed directly +to zoom and pan methods. It is not a global option +and will be ignored if passed to `Panzoom()` or `setOptions()`. `force` should be used sparingly to temporarily override and ignore options such as disablePan, disableZoom, and panOnlyWhenZoomed. -This option cannot be passed to the -Panzoom constructor or setOptions (to avoid -setting this option globally). ```js // Overrides disablePan and panOnlyWhenZoomed @@ -293,7 +294,7 @@ panzoom.zoom(1, { force: true }) }\*\*) -Defined in: [types.ts:91](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L91) +Defined in: [types.ts:92](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L92) On the first pointer event, when panning starts, the default Panzoom behavior is to call @@ -334,7 +335,7 @@ Panzoom(elem, { > `optional` **noBind**: `boolean` -Defined in: [types.ts:95](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L95) +Defined in: [types.ts:96](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L96) Skip binding the default Panzoom event listeners @@ -344,7 +345,7 @@ Skip binding the default Panzoom event listeners > `optional` **origin**: `string` -Defined in: [types.ts:109](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L109) +Defined in: [types.ts:110](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L110) **Change this at your own risk.** The `transform-origin` is the origin from which transforms are applied. @@ -364,7 +365,7 @@ And again, changing this for SVG in IE doesn't work at all. > `optional` **overflow**: `string` (Default: **"hidden"**) -Defined in: [types.ts:111](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L111) +Defined in: [types.ts:112](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L112) The overflow CSS value for the parent. Defaults to 'hidden' @@ -374,7 +375,7 @@ The overflow CSS value for the parent. Defaults to 'hidden' > `optional` **pinchAndPan**: `boolean` (Default: **false**) -Defined in: [types.ts:124](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L124) +Defined in: [types.ts:125](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L125) Set to true to enable panning during pinch zoom. Note: this is zooming to a point and panning in the same @@ -393,7 +394,7 @@ https://github.com/timmywil/panzoom/issues/606 > `optional` **setTransform**: (`elem`, `__namedParameters`, `_options`?) => `void` -Defined in: [types.ts:128](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L128) +Defined in: [types.ts:129](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L129) Set the transform using the proper prefix. @@ -439,7 +440,7 @@ const panzoom = Panzoom(elem, { > `optional` **silent**: `boolean` -Defined in: [types.ts:130](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L130) +Defined in: [types.ts:131](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L131) Silence all events @@ -449,7 +450,7 @@ Silence all events > `optional` **startScale**: `number` (Default: **1**) -Defined in: [types.ts:136](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L136) +Defined in: [types.ts:137](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L137) Scale used to set the beginning transform @@ -459,7 +460,7 @@ Scale used to set the beginning transform > `optional` **startX**: `number` (Default: **0**) -Defined in: [types.ts:132](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L132) +Defined in: [types.ts:133](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L133) X Value used to set the beginning transform @@ -469,7 +470,7 @@ X Value used to set the beginning transform > `optional` **startY**: `number` (Default: **0**) -Defined in: [types.ts:134](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L134) +Defined in: [types.ts:135](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L135) Y Value used to set the beginning transform @@ -479,7 +480,7 @@ Y Value used to set the beginning transform > `optional` **touchAction**: `string` (Default: **"none"**) -Defined in: [types.ts:146](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L146) +Defined in: [types.ts:147](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L147) This value is used to set touch-action on both the Panzoom element and its parent. @@ -491,7 +492,7 @@ cannot work at the same time. ## PanOptions (includes MiscOptions) -Defined in: [types.ts:151](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L151) +Defined in: [types.ts:152](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L152) ## Properties @@ -499,7 +500,7 @@ Defined in: [types.ts:151](https://github.com/timmywil/panzoom/blob/c77d09dcbe5c > `optional` **contain**: `"inside"` \| `"outside"` -Defined in: [types.ts:165](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L165) +Defined in: [types.ts:166](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L166) Contain the panzoom element either inside or outside the parent. @@ -519,7 +520,7 @@ empty space around the element will be shown. > `optional` **cursor**: `string` (Default: **"move"**) -Defined in: [types.ts:167](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L167) +Defined in: [types.ts:168](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L168) The cursor style to set on the panzoom element @@ -529,7 +530,7 @@ The cursor style to set on the panzoom element > `optional` **disablePan**: `boolean` (Default: **false**) -Defined in: [types.ts:173](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L173) +Defined in: [types.ts:174](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L174) Disable panning functionality. Note: disablePan does not affect focal point zooming or the contain option. @@ -541,7 +542,7 @@ The element will still pan accordingly. > `optional` **disableXAxis**: `boolean` (Default: **false**) -Defined in: [types.ts:175](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L175) +Defined in: [types.ts:176](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L176) Pan only on the Y axis @@ -551,7 +552,7 @@ Pan only on the Y axis > `optional` **disableYAxis**: `boolean` (Default: **false**) -Defined in: [types.ts:177](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L177) +Defined in: [types.ts:178](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L178) Pan only on the X axis @@ -561,7 +562,7 @@ Pan only on the X axis > `optional` **panOnlyWhenZoomed**: `boolean` (Default: **false**) -Defined in: [types.ts:181](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L181) +Defined in: [types.ts:182](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L182) Disable panning while the scale is equal to the starting value @@ -571,7 +572,7 @@ Disable panning while the scale is equal to the starting value > `optional` **relative**: `boolean` (Default: **false**) -Defined in: [types.ts:179](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L179) +Defined in: [types.ts:180](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L180) When passing x and y values to .pan(), treat the values as relative to their current values @@ -581,7 +582,7 @@ When passing x and y values to .pan(), treat the values as relative to their cur > `optional` **roundPixels**: `boolean` -Defined in: [types.ts:190](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L190) +Defined in: [types.ts:191](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L191) Round x and y values to whole numbers. This can help prevent images and text from looking blurry, @@ -592,7 +593,7 @@ zooming in when using this option. ## ZoomOptions (includes MiscOptions) -Defined in: [types.ts:193](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L193) +Defined in: [types.ts:194](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L194) ## Properties @@ -600,7 +601,7 @@ Defined in: [types.ts:193](https://github.com/timmywil/panzoom/blob/c77d09dcbe5c > `optional` **disableZoom**: `boolean` (Default: **false**) -Defined in: [types.ts:195](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L195) +Defined in: [types.ts:196](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L196) Disable zooming functionality @@ -610,7 +611,7 @@ Disable zooming functionality > `optional` **focal**: `object` -Defined in: [types.ts:202](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L202) +Defined in: [types.ts:203](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L203) Zoom to the given point on the panzoom element. This point is expected to be relative to @@ -631,7 +632,7 @@ to the parent dimensions. > `optional` **maxScale**: `number` (Default: **4**) -Defined in: [types.ts:206](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L206) +Defined in: [types.ts:207](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L207) The maximum scale when zooming @@ -641,7 +642,7 @@ The maximum scale when zooming > `optional` **minScale**: `number` (Default: **0.125**) -Defined in: [types.ts:204](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L204) +Defined in: [types.ts:205](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L205) The minimum scale when zooming @@ -651,7 +652,7 @@ The minimum scale when zooming > `optional` **step**: `number` (Default: **0.3**) -Defined in: [types.ts:208](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L208) +Defined in: [types.ts:209](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L209) The step affects zoom calculation when zooming with a mouse wheel, when pinch zooming, or when using zoomIn/zoomOut @@ -659,7 +660,7 @@ The step affects zoom calculation when zooming with a mouse wheel, when pinch zo These methods are available after initializing Panzoom. -Defined in: [types.ts:223](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L223) +Defined in: [types.ts:226](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L226) ## Properties @@ -667,7 +668,7 @@ Defined in: [types.ts:223](https://github.com/timmywil/panzoom/blob/c77d09dcbe5c > **bind**: () => `void` -Defined in: [types.ts:236](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L236) +Defined in: [types.ts:239](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L239) Bind the default down, move, and up event listeners to the Panzoom element. This does not normally need to be called. @@ -690,7 +691,7 @@ panzoom.bind() > **destroy**: () => `void` -Defined in: [types.ts:238](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L238) +Defined in: [types.ts:241](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L241) Remove all event listeners bound to the the Panzoom element @@ -704,7 +705,7 @@ Remove all event listeners bound to the the Panzoom element > **eventNames**: `object` -Defined in: [types.ts:244](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L244) +Defined in: [types.ts:247](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L247) This object exposes the event names used by Panzoom, depending on the current browser's support for @@ -728,7 +729,7 @@ Pointer or Touch events. > **getOptions**: () => `PanzoomOptions` -Defined in: [types.ts:250](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L250) +Defined in: [types.ts:253](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L253) Returns a _copy_ of the current options object @@ -742,7 +743,7 @@ Returns a _copy_ of the current options object > **getPan**: () => `object` -Defined in: [types.ts:246](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L246) +Defined in: [types.ts:249](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L249) Get the current x/y translation @@ -764,7 +765,7 @@ Get the current x/y translation > **getScale**: () => `number` -Defined in: [types.ts:248](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L248) +Defined in: [types.ts:251](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L251) Get the current scale @@ -778,7 +779,7 @@ Get the current scale > **handleDown**: (`event`) => `void` -Defined in: [types.ts:272](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L272) +Defined in: [types.ts:275](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L275) handleDown, handleMove, and handleUp are the exact event handlers that Panzoom @@ -816,7 +817,7 @@ document.addEventListener('pointerup', panzoom.handleUp) > **handleMove**: (`event`) => `void` -Defined in: [types.ts:273](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L273) +Defined in: [types.ts:276](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L276) #### Parameters @@ -834,7 +835,7 @@ Defined in: [types.ts:273](https://github.com/timmywil/panzoom/blob/c77d09dcbe5c > **handleUp**: (`event`) => `void` -Defined in: [types.ts:274](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L274) +Defined in: [types.ts:277](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L277) #### Parameters @@ -852,7 +853,7 @@ Defined in: [types.ts:274](https://github.com/timmywil/panzoom/blob/c77d09dcbe5c > **pan**: (`x`, `y`, `panOptions`?) => `[CurrentValues](#CurrentValues)` -Defined in: [types.ts:285](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L285) +Defined in: [types.ts:288](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L288) Pan the Panzoom element to the given x and y coordinates @@ -887,7 +888,7 @@ panzoom.pan(10, 10, { relative: true }) > **reset**: (`resetOptions`?) => `[CurrentValues](#CurrentValues)` -Defined in: [types.ts:298](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L298) +Defined in: [types.ts:301](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L301) Reset the pan and zoom to startX, startY, and startScale. Animates by default, ignoring the global option. @@ -916,7 +917,7 @@ panzoom.reset({ animate: false }) > **resetStyle**: () => `void` -Defined in: [types.ts:307](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L307) +Defined in: [types.ts:310](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L310) Reset the styles set on the Panzoom element and its parent (such as overflow, cursor, etc.) @@ -935,7 +936,7 @@ panzoom.resetStyle() > **setOptions**: (`options`?) => `void` -Defined in: [types.ts:320](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L320) +Defined in: [types.ts:323](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L323) Change any number of options on a Panzoom instance. Setting some options will have side-effects. @@ -952,7 +953,7 @@ panzoom.setOptions({ cursor: 'default' }) ##### options? -`PanzoomOptions` +`PanzoomGlobalOptions` #### Returns @@ -964,7 +965,7 @@ panzoom.setOptions({ cursor: 'default' }) > **setStyle**: (`name`, `value`) => `void` -Defined in: [types.ts:322](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L322) +Defined in: [types.ts:325](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L325) A convenience method for setting prefixed styles on the Panzoom element @@ -988,7 +989,7 @@ A convenience method for setting prefixed styles on the Panzoom element > **zoom**: (`scale`, `zoomOptions`?) => `[CurrentValues](#CurrentValues)` -Defined in: [types.ts:331](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L331) +Defined in: [types.ts:334](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L334) Zoom the Panzoom element to the given scale @@ -1017,7 +1018,7 @@ panzoom.zoom(2.2, { animate: true }) > **zoomIn**: (`zoomOptions`?) => `[CurrentValues](#CurrentValues)` -Defined in: [types.ts:342](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L342) +Defined in: [types.ts:345](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L345) Zoom in using the predetermined increment set in options. Animates by default, ignoring the global option. @@ -1044,7 +1045,7 @@ panzoom.zoomIn({ animate: false }) > **zoomOut**: (`zoomOptions`?) => `[CurrentValues](#CurrentValues)` -Defined in: [types.ts:353](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L353) +Defined in: [types.ts:356](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L356) Zoom out using the predetermined increment set in options. Animates by default, ignoring the global option. @@ -1071,7 +1072,7 @@ panzoom.zoomOut({ animate: false }) > **zoomToPoint**: (`scale`, `point`, `zoomOptions`?) => `[CurrentValues](#CurrentValues)` -Defined in: [types.ts:364](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L364) +Defined in: [types.ts:367](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L367) Zoom the Panzoom element to a focal point using the given pointer/touch/mouse event or constructed point. @@ -1112,7 +1113,7 @@ panzoom.zoomToPoint(1.2, pointerEvent) > **zoomWithWheel**: (`event`, `zoomOptions`?) => `[CurrentValues](#CurrentValues)` -Defined in: [types.ts:397](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L397) +Defined in: [types.ts:400](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L400) Zoom the Panzoom element to a focal point using the given WheelEvent @@ -1157,7 +1158,7 @@ elem.parentElement.addEventListener('wheel', function (event) { ## $1 -Defined in: [types.ts:216](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L216) +Defined in: [types.ts:219](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L219) ## Properties @@ -1165,7 +1166,7 @@ Defined in: [types.ts:216](https://github.com/timmywil/panzoom/blob/c77d09dcbe5c > `optional` **isSVG**: `boolean` -Defined in: [types.ts:220](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L220) +Defined in: [types.ts:223](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L223) --- @@ -1173,7 +1174,7 @@ Defined in: [types.ts:220](https://github.com/timmywil/panzoom/blob/c77d09dcbe5c > **scale**: `number` -Defined in: [types.ts:219](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L219) +Defined in: [types.ts:222](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L222) --- @@ -1181,7 +1182,7 @@ Defined in: [types.ts:219](https://github.com/timmywil/panzoom/blob/c77d09dcbe5c > **x**: `number` -Defined in: [types.ts:217](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L217) +Defined in: [types.ts:220](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L220) --- @@ -1189,7 +1190,7 @@ Defined in: [types.ts:217](https://github.com/timmywil/panzoom/blob/c77d09dcbe5c > **y**: `number` -Defined in: [types.ts:218](https://github.com/timmywil/panzoom/blob/c77d09dcbe5cbb3d9bc7dcbd1f2d8e4e99138ad1/src/types.ts#L218) +Defined in: [types.ts:221](https://github.com/timmywil/panzoom/blob/8e773ae5650ee83e61463a3f4441347468df3a61/src/types.ts#L221) ## Events diff --git a/src/panzoom.ts b/src/panzoom.ts index 7e0b9c9a..a1e74bd8 100644 --- a/src/panzoom.ts +++ b/src/panzoom.ts @@ -16,9 +16,9 @@ import type { PanOptions, PanzoomEvent, PanzoomEventDetail, + PanzoomGlobalOptions, PanzoomObject, PanzoomOptions, - PanzoomOptionsWithoutForce, ZoomOptions } from './types.js' @@ -27,7 +27,7 @@ import isExcluded from './isExcluded.js' import isSVGElement from './isSVGElement.js' import shallowClone from './shallowClone.js' -const defaultOptions: PanzoomOptions = { +const defaultOptions: PanzoomGlobalOptions = { animate: false, canvas: false, cursor: 'move', @@ -57,10 +57,7 @@ const defaultOptions: PanzoomOptions = { touchAction: 'none' } -function Panzoom( - elem: HTMLElement | SVGElement, - options?: PanzoomOptionsWithoutForce -): PanzoomObject { +function Panzoom(elem: HTMLElement | SVGElement, options?: PanzoomGlobalOptions): PanzoomObject { if (!elem) { throw new Error('Panzoom requires an element as an argument') } @@ -109,7 +106,7 @@ function Panzoom( setStyle(elem, 'transformOrigin', '') } - function setOptions(opts: PanzoomOptionsWithoutForce = {}) { + function setOptions(opts: PanzoomGlobalOptions = {}) { for (const key in opts) { if (opts.hasOwnProperty(key)) { options[key] = opts[key] @@ -178,7 +175,10 @@ function Panzoom( ) { const opts = { ...options, ...panOptions } const result = { x, y, opts } - if (!opts.force && (opts.disablePan || (opts.panOnlyWhenZoomed && scale === opts.startScale))) { + if ( + !panOptions?.force && + (opts.disablePan || (opts.panOnlyWhenZoomed && scale === opts.startScale)) + ) { return result } toX = parseFloat(toX as string) @@ -257,7 +257,7 @@ function Panzoom( function constrainScale(toScale: number, zoomOptions?: ZoomOptions) { const opts = { ...options, ...zoomOptions } const result = { scale, opts } - if (!opts.force && opts.disableZoom) { + if (!zoomOptions?.force && opts.disableZoom) { return result } @@ -309,7 +309,7 @@ function Panzoom( ) { const result = constrainScale(toScale, zoomOptions) const opts = result.opts - if (!opts.force && opts.disableZoom) { + if (!zoomOptions?.force && opts.disableZoom) { return } toScale = result.scale diff --git a/src/types.ts b/src/types.ts index b94bff77..c0ea4cbe 100644 --- a/src/types.ts +++ b/src/types.ts @@ -49,12 +49,13 @@ export interface MiscOptions { */ excludeClass?: string /** + * The `force` option can only be passed directly + * to zoom and pan methods. It is not a global option + * and will be ignored if passed to `Panzoom()` or `setOptions()`. + * * `force` should be used sparingly to temporarily * override and ignore options such as disablePan, * disableZoom, and panOnlyWhenZoomed. - * This option cannot be passed to the - * Panzoom constructor or setOptions (to avoid - * setting this option globally). * * ```js * // Overrides disablePan and panOnlyWhenZoomed @@ -211,7 +212,9 @@ export interface ZoomOnlyOptions { export type PanOptions = MiscOptions & PanOnlyOptions export type ZoomOptions = MiscOptions & ZoomOnlyOptions export type PanzoomOptions = PanOptions & ZoomOptions & MiscOptions -export type PanzoomOptionsWithoutForce = PanOptions & ZoomOptions & Omit +export type PanzoomGlobalOptions = { + [K in keyof PanzoomOptions as K extends 'force' ? never : K]: PanzoomOptions[K] +} export interface CurrentValues { x: number @@ -317,7 +320,7 @@ export interface PanzoomObject { * panzoom.setOptions({ cursor: 'default' }) * ``` */ - setOptions: (options?: PanzoomOptions) => void + setOptions: (options?: PanzoomGlobalOptions) => void /** A convenience method for setting prefixed styles on the Panzoom element */ setStyle: (name: string, value: string) => void /** diff --git a/tasks/docs.js b/tasks/docs.js index 5a45ee0b..19dd31d7 100644 --- a/tasks/docs.js +++ b/tasks/docs.js @@ -29,10 +29,7 @@ function removeLinks(data) { function addLinks(data) { return data .replace(/PanzoomOptions\b/g, '[PanzoomOptions](#PanzoomOptions)') - .replace( - /PanzoomOptionsWithoutForce/g, - '[PanzoomOptionsWithoutForce](#PanzoomOptionsWithoutForce)' - ) + .replace(/PanzoomGlobalOptions\b/g, '[PanzoomGlobalOptions](#PanzoomGlobalOptions)') .replace(/PanOptions/g, '[PanOptions](#PanOptions)') .replace(/ZoomOptions/g, '[ZoomOptions](#ZoomOptions)') .replace(/MiscOptions/g, '[MiscOptions](#MiscOptions)') @@ -71,7 +68,7 @@ data += getModuleFunction('default').replace(/default/g, 'Panzoom') // Get default options const source = read('../src/panzoom.ts') -const defaultProps = /const defaultOptions: PanzoomOptions = ({[^]+?\n})/.exec(source)[1] +const defaultProps = /const defaultOptions: PanzoomGlobalOptions = ({[^]+?\n})/.exec(source)[1] const parsedDefaults = {} defaultProps.replace(/(\w+): ([^]+?)(?:,\n|\n})/g, (all, key, value) => { parsedDefaults[key] = value.replace(/'/g, '"') @@ -86,7 +83,7 @@ function addDefaults(data) { const panzoomOptions = '\n\n## `PanzoomOptions`\n\nIncludes `MiscOptions`, `PanOptions`, and `ZoomOptions`\n\n' + - '\n\n## `PanzoomOptionsWithoutForce`\n\nIdentical to PanzoomOptions, but excludes the `force` option.\n\n' + + '\n\n## `PanzoomGlobalOptions`\n\nIdentical to PanzoomOptions, but excludes the `force` option.\n\n' + getInterfaceContent( 'MiscOptions.md', '## MiscOptions\n\nThese options can be passed to `Panzoom()`, as well as any pan or zoom function. One exception is `force`, which can only be passed to methods like `pan()` or `zoom()`, but not `Panzoom()` or `setOptions()` as it should not be set globally.' diff --git a/test/unit/panzoom.test.ts b/test/unit/panzoom.test.ts index 42971501..c63e5f9c 100644 --- a/test/unit/panzoom.test.ts +++ b/test/unit/panzoom.test.ts @@ -389,6 +389,32 @@ QUnit.module('Panzoom', () => { assert.strictEqual(pan.y, 1) document.body.removeChild(div) }) + QUnit.test('force option ignored when passed to Panzoom()', (assert) => { + const div = document.createElement('div') + document.body.appendChild(div) + const panzoom = Panzoom(div, { force: true }) + panzoom.pan(1, 1) + const pan = panzoom.getPan() + assert.strictEqual(pan.x, 1) + assert.strictEqual(pan.y, 1) + document.body.removeChild(div) + }) + QUnit.test('force option ignored when passed to setOptions()', (assert) => { + const div = document.createElement('div') + document.body.appendChild(div) + const panzoom = Panzoom(div) + panzoom.setOptions({ force: true }) + panzoom.pan(1, 1) + const pan = panzoom.getPan() + assert.strictEqual(pan.x, 1) + assert.strictEqual(pan.y, 1) + panzoom.setOptions({ disablePan: true }) + panzoom.pan(2, 2, { force: true }) // Still works at method level + const pan2 = panzoom.getPan() + assert.strictEqual(pan2.x, 2) + assert.strictEqual(pan2.y, 2) + document.body.removeChild(div) + }) }) QUnit.test('calls the handleStartEvent option', (assert) => { return new Promise((resolve) => {