Waapi-timing-properties NPM

WAAPI timing properties

List of timing properties and their possible values for animation effects used in Web Animations API.

It can be used to validate() and sanitize() options passed to Element.animate(), KeyframeEffectReadOnly() and KeyframeEffect(). Here's an example.

DEMO and its source code.

Install

$ yarn add waapi-timing-properties

$ npm install waapi-timing-properties

Usage

Import all functionality into one object:

import * as WTProperties from 'waapi-timing-properties'

Or import only what you need:

import { properties, propertiesNames, sanitize, validate } from 'waapi-timing-properties'

Or load from CDN:

<!-- Either -->
<script src="https://unpkg.com/waapi-timing-properties"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/waapi-timing-properties@latest/dist/wtproperties.js"></script>

WTProperties.properties is an object containing properties names and their possible values.

The structure of the object is this:

WTProperties.propertiesNames.forEach((property) => {
  const object = WTProperties.properties[property]
})

object.default is the default value of the property.

object.type is either 'Number' or 'String'.

If object.type === 'Number' then

object.min is its minimal possible value

object.max is its maximal possible value

If object.type === 'String' then

object.values is an array of possible values.

For easing property there is also

object.valuesCubicBezier object which contains cubic-bezier equivalents of linear, ease, ease-in, ease-out and ease-in-out

and

object.valuesSteps object which contains steps equivalents of step-start and step-end

WTProperties.propertiesNames is an array containing only properties names.

WTProperties.sanitize has two optional arguments:

WTProperties.sanitize(objectArrayOrStringToCheck, checkValues = true, returnDefault = true)

WTProperties.validate also has two optional arguments:

WTProperties.validate(objectArrayOrStringToCheck, checkValues = true, returnFirstInvalidProperty = false)

Let's sanitize and validate some options:

const options = {
  duration: -1000,
  easing: 'not easy',
  iterations: 3,
  someInvalidOption: 123,
}

Use WTProperties.sanitize(options) to remove properties with invalid names and replace properties with valid names but invalid values with their default values:

WTProperties.sanitize(options) ===
  {
    duration: 0,
    easing: 'linear',
    iterations: 3,
  }
WTProperties.validate(options) === true

Use sanitize(options, true, false) to remove all properties with invalid names and/or values:

WTProperties.sanitize(options, true, false) ===
  {
    iterations: 3,
  }
WTProperties.validate(options) === true

Use sanitize(options, false) to remove only properties with invalid names without checking their values:

WTProperties.sanitize(options, false) ===
  {
    duration: -1000,
    easing: 'not easy',
    iterations: 3,
  }
WTProperties.validate(options) === false
WTProperties.validate(options, false) === true

Set the third argument of validate() - returnFirstInvalidProperty to true to return string containing first invalid property instead of boolean when the result is false:

This can be useful for writing tests. Here's an example.

const options = {
  duration: -1000,
  easing: 'not easy',
  iterations: 3,
  someInvalidOption: 123,
}
WTProperties.validate(options) === false
WTProperties.validate(options, true, true) === 'duration: -1000'
WTProperties.validate(options, false) === false
WTProperties.validate(options, false, true) === 'someInvalidOption: 123'

options can be array of properties names to check or a string (a single property name). In this case the optional arguments have no effect.

Play with the DEMO for better understanding of how it works.

Here's the list of all the properties with their possible values and defaults:

id
Possible values:
- Any string
Default:
- No default value
direction
Possible values:
- normal
- reverse
- alternate
- alternate-reverse
Default:
- normal
duration
Possible values:
- Any positive number or 0
Default:
- 0
easing
Possible values:
- linear
- ease
- ease-in
- ease-out
- ease-in-out
- cubic-bezier(x1, y1, x2, y2) where x1 and x2 are numbers between 0 and 1, y1 and y2 are any numbers
- step-start
- step-end
- steps(number_of_steps[, direction]) where number_of_steps is an integer greater than 0 and optional direction is one of end, start, jump-both, jump-none, jump-end, jump-start
Default:
- linear
endDelay
Possible values:
- Any positive number or 0
Default:
- 0
fill
Possible values:
- none
- forwards
- backwards
- both
- auto
Default:
- auto
iterationStart
Possible values:
- Any positive number or 0
Default:
- 0
iterations
Possible values:
- Any positive number or 0 or Infinity
Default:
- 1
composite
Possible values:
- add
- accumulate
- replace
- auto
Default:
- replace
iterationComposite
Possible values:
- accumulate
- replace
Default:
- replace