Animation

Installation

  yarn add @chewy/kib-foundations

Import

  @use '~@chewy/kib-foundations/src/animation';

Functions

get-properties

@function get-properties($theme: settings.$preferred-theme) { ... }@function get-properties($theme: settings.$preferred-theme) { 
  $theme-map: common.get-theme-map(settings.$themes, $theme);

  @each $key, $value in $theme-map {
    $theme-map: map.set($theme-map, 'animation', $key, $value);
  }

  @return common.flatten-map($theme-map);
 }
Description

Returns a theme's animations as a flattened map with kebab-cased names

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$theme

Name of the theme

Stringsettings.$preferred-theme
Returns
Map

Final flattened map

Requires

-get-animation-value

@function -get-animation-value($theme: settings.$default-theme, $alias) { ... }@function -get-animation-value($theme: settings.$default-theme, $alias) { 
  $theme-map: common.get-theme-map(settings.$themes, $theme);
  $has-key: map.has-key($theme-map, $path...);

  @if not $has-key {
    @error "Animation value (#{$path}) not found.";
  }

  @return map.get($theme-map, $path...);
 }
Description

Retrieves a animation style property value

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$theme

Name of the theme

Stringsettings.$default-theme
$alias

Alias of animation unit

String none
Returns
Number

Spacing value from the theme

Throws
  • Animation value (#{$path}) not found.

Requires
Used by

-get-animation-property

@function -get-animation-property($path) { ... }@function -get-animation-property($path) { 
  $theme-map: common.get-theme-map(settings.$themes, settings.$preferred-theme);

  @if not map.has-key($theme-map, $path...) {
    @error "The animation property (#{$path}) does not exist.";
  }

  $property: common.get-property-name('animation', $path...);
  $fallback: -get-animation-value(settings.$preferred-theme, $path...);

  @return string.unquote('var(#{$property}, #{$fallback})');
 }
Description

Get a single animation style property definition.

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$path

The map path to the desired property definition.

List none
Returns
List or String or Number

Return the value of the animation property.

Throws
  • The animation property (#{$path}) does not exist.

Requires

-get-color

@function -get-color($theme: common.$default-theme, $colorset: settings.$default-colorset, $path...) { ... }@function -get-color($theme: common.$default-theme, $colorset: settings.$default-colorset, $path...) { 
  $theme-map: common.get-theme-map(tokens.$chirp-themes, $theme);
  $is-default: $colorset == settings.$default-colorset;
  $has-key: map.has-key($theme-map, $colorset, $path...);

  @if $has-key == false {
    @if $is-default == false {
      @warn "Attempting to fallback to '#{settings.$default-colorset}' colors";
      @return -get-color($theme, settings.$default-colorset, $path...);
    } @else {
      @error "Color not found: '#{$path}'";
    }
  }

  @return map.get($theme-map, $colorset, $path...);
 }
Description

Retrieves a color from a theme

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$theme

The name of the theme to lookup

Stringcommon.$default-theme
$colorset

'light' and 'dark' colorset

Stringsettings.$default-colorset
$path...

Comma separated path to a theme's color

List none
Returns
Color

Color value from the theme

Throws
  • Color not found:

Requires

-get-valid-path

@function -get-valid-path($path...) { ... }@function -get-valid-path($path...) { 
  $property: common.get-property-name($path...);

  @if map.has-key(settings.$deprecated-property-names, $property) {
    $new-path: map.get(settings.$deprecated-property-names, $property);
    @warn "Color '#{$path}' is deprecated, please switch to '#{$new-path}'";
    @return $new-path;
  }

  @return $path;
 }
Description

Checks for deprecated color paths and if so, updates to the correct color path

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$path...

Comma separated path to a theme's color

List none
Returns
List

Comma separated path to a theme's color

Requires

get

@function get($path...) { ... }@function get($path...) { 
  @return get-property($path...);
 }
Description

Creates a custom property reference from a color path

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$path...

Comma separated path to a theme's color

List none
Returns
String

CSS var() function with a fallback color

Example

Basic usage

@use '~@chewy/kib-foundations/src/color';

.inverse-content {
  background-color: color.get('ui-bg', '06');
  color: color.get('text', 'inverse');
}
Used by

-get-themes

@function -get-themes($tokens) { ... }@function -get-themes($tokens) { 
  $themes: ();

  @each $name, $theme in $tokens {
    $themes: map.set($themes, $name, map.get($theme, 'animation'));
  }

  @return $themes;
 }
Description

Get map of all animation themes Defined here to avoid a module loop.

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$tokens

Animation tokens map

Map none
Returns
Map

Border themes definitions map

Requires

Variables

preferred-theme

$preferred-theme: common.$preferred-theme !default;
Description

Name of the preferred theme to look for properties first. If not found it will fallback to common.$default-theme.

Type

String

page-entry-movement

$page-entry-movement: unit.rem(170px);
Description

Page top starting position

Type

Number

page-fade-transition-duration

$page-fade-transition-duration: 1000ms !default;
Description

Page fade transitions duration

Type

Number

page-slide-transition-duration

$page-slide-transition-duration: 500ms !default;
Description

Page slide Group transitions duration

Type

Number

themes

$themes: (...);$themes: -get-themes(tokens.$chirp-animation);
Description

Map of animation themes

Type

Map

Used by

aliases

$aliases: (...);$aliases: ();
Description

Map of animation style aliases to facilitate deprecation and removal of animation styles Currently a placeholder.

Type

Map

Used by

deprecated-property-names

$deprecated-property-names: (...);$deprecated-property-names: ();
Description

Deprecated color paths

Type

Map

Used by

Mixins

custom-properties

@mixin custom-properties($theme: 'base', $deprecated: false, $overrides) { ... }@mixin custom-properties($theme: 'base', $deprecated: false, $overrides) { 
  $animation-properties: functions.get-properties($theme);

  @if $overrides {
    $animation-properties: map.deep-merge($animation-properties, $overrides);
  }

  @each $key, $value in $animation-properties {
    #{common.get-property-name($key)}: $value;
  }
 }
Description

Generates CSS Custom Properties for a Chirp theme's animation tokens

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$theme

The name of the theme to look up

String'base'
$deprecated

Includes custom properties for deprecated animation styles

Boolfalse
$overrides

Map that overrides any matching values within the theme

Map none
Example

Apply all available properties to the :root of the page

@use '~@chewy/kib-foundations/src/animation';

:root {
  @include animation.custom-properties;
}

Apply properties to a selector

@use '~@chewy/kib-foundations/src/animation';

.chirp-animation {
  @include animation.custom-properties;
}

Override a animation property

@use '~@chewy/kib-foundations/src/animation';

.chirp-animation-custom {
  @include animation.custom-properties($overrides: ('text-typeface': Roboto));
}
Requires

apply

@mixin apply($name, $variant, $alternate) { ... }@mixin apply($name, $variant, $alternate) { 
  $variant: functions.get-last-item($animation-style);
  $animation-style: functions.remove-last-item($animation-style);
  $animations: common.get-theme-map(settings.$themes, settings.$preferred-theme);
  $alias: $animation-style;

  $style: map.get($animations, $alias...);

  $not-rendered: true;
  @each $name in map.keys($style) {
    $is-variant-match: if(str-index($name, '-#{$variant}'), true, false);
    $is-subtle: if(str-index($name, '-subtle'), true, false);
    $is-standard: if(str-index($name, '-standard'), true, false);
    $value: map.get($style, $name);
    $valueType: '';

    @if $is-variant-match {
      @if $is-subtle {
        $valueType: common.str-replace($name, '-subtle', '');
      } @else if $is-standard {
        $valueType: common.str-replace($name, '-standard', '');
      } @else {
        $valueType: $name;
      }
    }

    @if $valueType == 'duration' or $valueType == 'function' {
      $fallback: #{map.get($style, $name)};
      $value: string.unquote('var(#{$value}, #{$fallback})');
      --animation-press-scale-#{$valueType}: #{$value};
    }
    @else_if ($valueType == "amount" or $valueType == "amount-hover") and $is-variant-match {
      $property: common.get-property-name('animation', append($alias, $name));
      $fallback: '';
      $value: string.unquote('var(#{$property}, #{$fallback})');

      --animation-press-scale-#{$valueType}: #{$value};
    }
  }

  $animation-press-scale-amount-standard: 0;
  $animation-press-scale-amount-subtle: 0;
  $animation-press-scale-amount-standard-hover: 0;
  $animation-press-scale-amount-subtle-hover: 0;

  @each $name in map.keys($style) {
    $is-variant-match: if(str-index($name, '-#{$variant}'), true, false);
    $is-variant-match-string: if(str-index($name, '-#{$variant}'), 'true', 'false');
    $is-subtle: if(str-index($name, '-subtle'), true, false);
    $is-standard: if(str-index($name, '-standard'), true, false);
    $value: map.get($style, $name);
    $valueType: '';

    @if $is-variant-match {
      @if $is-subtle {
        $valueType: common.str-replace($name, '-subtle', '');
      } @else if $is-standard {
        $valueType: common.str-replace($name, '-standard', '');
      } @else {
        $valueType: $name;
      }
    }

    @if ($is-subtle or $is-standard) {
      @if $is-variant-match {
        --animation-press-scale-#{$valueType}: #{map.get($style, $name)};
      }
    } @else {
      --animation-press-scale-#{$name}: #{map.get($style, $name)};
    }
  }

  // duration
  transition: transform var(--animation-press-scale-duration, #{map.get($style, 'duration')})
    var(--animation-press-scale-function, #{map.get($style, 'function')});

  @media (hover: hover) and (pointer: fine) {
    &:hover {
      transform: scale3d(
        var(--animation-press-scale-amount-hover),
        var(--animation-press-scale-amount-hover),
        1
      );
    }
  }

  // normal
  &:active {
    transform: scale3d(var(--animation-press-scale-amount), var(--animation-press-scale-amount), 1);
  }

  // reduced motion
  @media (prefers-reduced-motion: reduce) {
    transition: none;
  }

  @each $name in map.keys($style) {
    $is-variant-match: if(str-index($name, '-#{$variant}'), true, false);
    $is-variant-match-string: if(str-index($name, '-#{$variant}'), 'true', 'false');
    $is-subtle: if(str-index($name, '-subtle'), true, false);
    $is-standard: if(str-index($name, '-standard'), true, false);
    $value: map.get($style, $name);
    $valueType: '';
    $newNewName: str-quote(common.str-replace(str-quote($name), '-subtle', ''));

    @if $is-variant-match {
      @if $is-subtle {
        $valueType: common.str-replace($name, '-subtle', '');
      } @else if $is-standard {
        $valueType: common.str-replace($name, '-standard', '');
      } @else {
        $valueType: $name;
      }
    }
  }
 }
Description

Generate styles using custom properties from a defined animation style.

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$name

The name of the animation style

String none
$variant

The variant name of the animation style

String none
$alternate

Applies the deprecated alternate animation style definition

Boolean none
Example

Apply styles for a animation style definition

@use '~@chewy/kib-foundations/src/animation';

.my-custom-class {
  @include animation.style-as('display-1');


}

Apply styles for a variant animation style

@use '~@chewy/kib-foundations/src/animation';

.my-custom-class {
  @include animation.style-as('editorial-heading-2', 'strong');
}

Apply styles for a deprecated alternate animation style definition

@use '~@chewy/kib-foundations/src/animation';

.my-custom-class {
  @include animation.style-as('display-1', $alternate: true);
}
Requires

page-entry-common

@mixin page-entry-common($delay: '0') { ... }@mixin page-entry-common($delay: '0') { 
  animation-delay: $delay;
  animation-fill-mode: both;
 }
Description

Page entry shared attributes

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$delay

delay preset

Number'0'
Requires

page-entry-fade-up

@mixin page-entry-fade-up($delay: '0', $fade-duration: 'settings.$fade-transition-duration', $slide-duration: 'settings.$slide-transition-duration') { ... }@mixin page-entry-fade-up($delay: '0', $fade-duration: 'settings.$fade-transition-duration', $slide-duration: 'settings.$slide-transition-duration') { 
  @include page-entry-common($delay);

  animation-name: kib-animation-page-entry-fade-in, kib-animation-page-entry-slide-up;
  animation-duration: $fade-duration, $slide-duration;

  @media (prefers-reduced-motion: reduce) {
    animation: none;
  }
 }
Description

Page entry fade up transition

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$delay

delay preset

Number'0'
$fade-duration

fade duration preset

Number'settings.$fade-transition-duration'
$slide-duration

slide duration preset

Number'settings.$slide-transition-duration'
Requires

page-entry-fade-in

@mixin page-entry-fade-in($delay: '0', $duration: 'settings.$fade-transition-duration') { ... }@mixin page-entry-fade-in($delay: '0', $duration: 'settings.$fade-transition-duration') { 
  @include page-entry-common($delay);

  animation-name: kib-animation-page-entry-fade-in;
  animation-duration: $duration;

  @media (prefers-reduced-motion: reduce) {
    animation: none;
  }
 }
Description

Page entry fade in transition

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$delay

delay preset

Number'0'
$duration

duration preset

Number'settings.$fade-transition-duration'
Requires

page-entry-slide-up

@mixin page-entry-slide-up($delay: '0', $duration: 'settings.$slide-transition-duration') { ... }@mixin page-entry-slide-up($delay: '0', $duration: 'settings.$slide-transition-duration') { 
  @include page-entry-common($delay);

  animation-name: kib-animation-page-entry-slide-up;
  animation-duration: $duration;

  @media (prefers-reduced-motion: reduce) {
    animation: none;
  }
 }
Description

Page entry slide up transition

Parameters
Parameters
parameter Nameparameter Descriptionparameter Typeparameter Default value
$delay

delay preset

Number'0'
$duration

duration preset

Number'settings.$slide-transition-duration'
Requires