Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

waapi-timing-properties

1.4.3 • Public • Published

WAAPI timing properties

code style: prettier Dependency Status devDependencies Status codecov Build Status

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.

Install

npm i waapi-timing-properties

DownloadsWeekly Downloads

17

Version

1.4.3

License

MIT

Unpacked Size

42.6 kB

Total Files

10

Last publish

Collaborators

  • avatar