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

or

$ 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

Development

Build the bundle for browsers into ./dist folder:

yarn build

Rebuild the bundle when its source files change on disk:

yarn watch

Run tests:

yarn test

Lint:

yarn lint

Fix linting and style errors:

yarn fix

Update dependencies:

yarn up

Generate changelog based on commit messages:

yarn c

To use the above command conventional-changelog-cli must be installed globally. Follow the recommended workflow.