Javascript utilities
> This is a collection of generic Javascript utilities to help develpment on MONOGRID sites.
``bash`
npm install --save @monogrid/js-utils
or
`bash`
yarn add @monogrid/js-utils
A collection of File related utilities.
An utility function to normalize the mouseWheel input in the browser.
A collection of Number related utilities
A collection of Object related utilities
Holds information on the Platform where this code is run
A collection of Vue.js related utilities
* FileUtils
* ~downloadFile(content, fileName, contentType)
* [~loadFile([accept])](#module_FileUtils..loadFile) ⇒ Promise.<Array>
* ~loadJSON() ⇒ Promise.<String>
* ~loadImage() ⇒ Promise.<Image>
Kind: inner method of FileUtils
| Param | Type | Description |
| --- | --- | --- |
| content | String | The content to be downloaded. |
| fileName | String | The name of the file downloaded into the user's PC. |
| contentType | String | The file type. |
Kind: inner method of FileUtils
Returns: Promise.<Array> - Array of files selected by the user.
| Param | Type | Description |
| --- | --- | --- |
| [accept] | String | Accept string to restrict file selection to certain file types. |
Kind: inner method of FileUtils
Returns: Promise.<String> - The parsed JSON file.
Kind: inner method of FileUtils
Returns: Promise.<Image> - The selected image object.
If you need to react to the mouse wheel in a predictable way, this code is
like your bestest friend. hugs
As of today, there are 4 DOM event types you can listen to:
'wheel' -- Chrome(31+), FF(17+), IE(9+)
'mousewheel' -- Chrome, IE(6+), Opera, Safari
'MozMousePixelScroll' -- FF(3.5 only!) (2010-2013) -- don't bother!
'DOMMouseScroll' -- FF(0.9.7+) since 2003
So what to do? The is the best:
normalizeWheel.getEventType()
In your event callback, use this code to get sane interpretation of the
deltas. This code will return an object with properties:
spinX -- normalized spin speed (use for zoom) - x plane
spinY -- " - y plane
pixelX -- normalized distance (to pixels) - x plane
pixelY -- " - y plane
Wheel values are provided by the browser assuming you are using the wheel to
scroll a web page by a number of lines or pixels (or pages). Values can lety
significantly on different platforms and browsers, forgetting that you can
scroll at different speeds. Some devices (like trackpads) emit more events
at smaller increments with fine granularity, and some emit massive jumps with
linear speed or acceleration.
This code does its best to normalize the deltas for you:
- spin is trying to normalize how far the wheel was spun (or trackpad
dragged). This is super useful for zoom support where you want to
throw away the chunky scroll steps on the PC and make those equal to
the slow and smooth tiny steps on the Mac. Key data: This code tries to
resolve a single slow step on a wheel to 1.
- pixel is normalizing the desired scroll delta in pixel units. You'll
get the crazy differences between browsers, but at least it'll be in
pixels!
- positive value indicates scrolling DOWN/RIGHT, negative UP/LEFT. This
should translate to positive value zooming IN, negative zooming OUT.
This matches the newer 'wheel' event.
Why are there spinX, spinY (or pixels)?
- spinX is a 2-finger side drag on the trackpad, and a shift + wheel turn
with a mouse. It results in side-scrolling in the browser by default.
- spinY is what you expect -- it's the classic axis of a mouse wheel.
- I dropped spinZ/pixelZ. It is supported by the DOM 3 'wheel' event and
probably is by browsers in conjunction with fancy 3D controllers .. but
you know.
Implementation info:
Examples of 'wheel' event if you scroll slowly (down) by one step with an
average mouse:
OS X + Chrome (mouse) - 4 pixel delta (wheelDelta -120)
OS X + Safari (mouse) - N/A pixel delta (wheelDelta -12)
OS X + Firefox (mouse) - 0.1 line delta (wheelDelta N/A)
Win8 + Chrome (mouse) - 100 pixel delta (wheelDelta -120)
Win8 + Firefox (mouse) - 3 line delta (wheelDelta -120)
On the trackpad:
OS X + Chrome (trackpad) - 2 pixel delta (wheelDelta -6)
OS X + Firefox (trackpad) - 1 pixel delta (wheelDelta N/A)
On other/older browsers.. it's more complicated as there can be multiple and
also missing delta values.
The 'wheel' event is more standard:
http://www.w3.org/TR/DOM-Level-3-Events/#events-wheelevents
The basics is that it includes a unit, deltaMode (pixels, lines, pages), and
deltaX, deltaY and deltaZ. Some browsers provide other values to maintain
backward compatibility with older events. Those other values help us
better normalize spin speed. Example of what the browsers provide:
| event.wheelDelta | event.detail
------------------+------------------+--------------
Safari v5/OS X | -120 | 0
Safari v5/Win7 | -120 | 0
Chrome v17/OS X | -120 | 0
Chrome v17/Win7 | -120 | 0
IE9/Win7 | -120 | undefined
Firefox v4/OS X | undefined | 1
Firefox v4/Win7 | undefined | 3
Kind: inner method of normalizeWheel
* NumberUtils
* ~lerpNumber(v0, v1, t) ⇒ Number
* ~range(oldValue, oldMin, oldMax, newMin, newMax, clamped)
* ~clamp(value, min, max) ⇒ Number
* ~map(value, min, max)
* ~angleDistance(alpha, beta)
* ~angleDistanceSign(alpha, beta)
* ~smoothstep(min, max, value) ⇒ Number
* ~mix(value1, value2, percent)
* ~sign(value) ⇒ Number
* [~randByPower(min, max, power, [rd])](#module_NumberUtils..randByPower)
* ~mapToPower(value, min, max, power)
* ~distance(x1, y1, x2, y2) ⇒ Number
* ~distanceCompare(x1, y1, x2, y2) ⇒ Number
Kind: inner method of NumberUtils
Returns: Number - Interpolation between v0 and v1 based on t
| Param | Type | Description |
| --- | --- | --- |
| v0 | Number | Initial value |
| v1 | Number | Final value |
| t | Number | zero to one |
Kind: inner method of NumberUtils
| Param | Type |
| --- | --- |
| oldValue | \* |
| oldMin | \* |
| oldMax | \* |
| newMin | \* |
| newMax | \* |
| clamped | \* |
Kind: inner method of NumberUtils
Returns: Number - A number clamped between min and max
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| value | Number | | The value to be clamped. |
| min | Number | 0 | Minimum value. |
| max | Number | 1 | Maximum value. |
Kind: inner method of NumberUtils
| Param | Type |
| --- | --- |
| value | Number |
| min | Number |
| max | Number |
Kind: inner method of NumberUtils
| Param | Type |
| --- | --- |
| alpha | Number |
| beta | Number |
Kind: inner method of NumberUtils
| Param | Type |
| --- | --- |
| alpha | Number |
| beta | Number |
Kind: inner method of NumberUtils
Returns: Number - Value of the interpolation
| Param | Type | Description |
| --- | --- | --- |
| min | Number | Initial value |
| max | Number | Final Value |
| value | Number | - |
Kind: inner method of NumberUtils
| Param | Type | Description |
| --- | --- | --- |
| value1 | Number | Minimum value. |
| value2 | Number | Maximum value. |
| percent | Number | zero to one value percent |
Kind: inner method of NumberUtils
Returns: Number - 0 if value is zero, -1 if value is less than 0, 1 otherwise
| Param | Type | Description |
| --- | --- | --- |
| value | Number | a number to be tested |
Kind: inner method of NumberUtils
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| min | Number | | |
| max | Number | | |
| power | Number | | |
| [rd] | Number | Math.random | Optional Random number generator |
Kind: inner method of NumberUtils
| Param | Type |
| --- | --- |
| value | Number |
| min | Number |
| max | Number |
| power | Number |
Kind: inner method of NumberUtils
Returns: Number - Distance between x1,y1 and x2,y2
| Param | Type | Description |
| --- | --- | --- |
| x1 | Number | x coordinate of first point |
| y1 | Number | y coordinate of first point |
| x2 | Number | x coordinate of second point |
| y2 | Number | y coordinate of second point |
Kind: inner method of NumberUtils
Returns: Number - bogus distance between x1,y1 and x2,y2. DO NOT USE WHEN A REAL DISTANCE IS NEEDED
| Param | Type | Description |
| --- | --- | --- |
| x1 | Number | x coordinate of first point |
| y1 | Number | y coordinate of first point |
| x2 | Number | x coordinate of second point |
| y2 | Number | y coordinate of second point |
Kind: inner method of ObjectUtils
Returns: Boolean - true if the object is a plain object, false otherwise.
| Param | Type | Description |
| --- | --- | --- |
| o | \* | The object to be tested. |
Properties
| Name | Type | Description |
| --- | --- | --- |
| mobile | Boolean | Device is a mobile (includes tablets and phones) |
| phone | Boolean | Device is a phone (excludes tablets) |
| tablet | Boolean | Device is a tablet (excludes phones) |
| android | Boolean | Device is Android based |
| ios | Boolean | Device is iOS based |
| ipad | Boolean | Device is an iPad |
| iphone | Boolean | Device is an iPhone |
| wphone | Boolean | Device is an Windows Phone |
| edge | Boolean | Browser is Microsoft Edge |
| firefox | Boolean | Browser is Mozilla Firefox |
| ie11 | Boolean | Browser is Microsoft Internet Explorer 11 |
| safari | Boolean | Browser is Safari |
| prerenderer | Boolean | Page is visited by a prerenderer (like Phantom JS) |
| volume | Boolean | Device supports volume setting via js (iOS doesn't support this) |
Kind: inner method of VueUtils
| Param | Type |
| --- | --- |
| value | Object |
| model | Object |
| Name | Type | Description |
| --- | --- | --- |
| value | Number | The real value of the number. |
| target | Number | The desired value of the number. |
| speed | Number | The speed at which the ElasticNumber will make value reach target. |
* ElasticNumber
* new ElasticNumber()
* .update(delta)
Example
`js
constructor () {
this.myNumber = new ElasticNumber();
this.time = new Date().getTime()
}
onUpdate () {
const now = new Date().getTime()
const delta = now - this.time
this.myNumber.target = Math.random() * 100
this.myNumber.update(delta);
this.mySprite.x = this.myNumber.value
this.time = now
}
`
Kind: static method of ElasticNumber
| Param | Type | Description |
| --- | --- | --- |
| delta | Number | delta time in milliseconds |
| Name | Type |
| --- | --- |
| orientationX | Number |
| orientationY | Number |
| enabled | Boolean |
The values are updated every frame and the system stops updating
if it determines that the device does not have gyroscope capabilities.
* RAF
* new RAF()
* .add(listener)
* .remove(listener)
Example
`js
import RAF from 'js-utils'
constructor () {
RAF.add(this.onUpdate)
}
onUpdate () {
// do stuff
}
onDestroy () {
RAF.remove(this.onUpdate)
}
``
Kind: instance method of RAF
| Param | Type | Description |
| --- | --- | --- |
| listener | function | A subscriber function |
Kind: instance method of RAF
| Param | Type | Description |
| --- | --- | --- |
| listener | function | A subscriber function |
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.