CSS Transition

This is a mechanism to trigger CSS transitions when property values change.

cssTransition

The cssTransition function creates a function that invokes a CSS transition. The created function can be used as a callback for property update monitoring.

const transition = cssTransition("transition")
const show = (state) => ({
  ".modal": {
    "class-is-open": state.modalIsOpen, 
    "&class-is-open": transition
  }
})
.modal.is-open {
  display: block;
  opacity: 1;
}
.modal.transition-enter {  /* when modal open */
  opacity: 0;
  display: block;
}
.modal.transition-enter-active {
  transition: opacity 0.2s;
  opacity: 1;
}
.modal.transition-exit {  /* when modal close */
  display: block;
}
.modal.transition-exit-active {
  transition: opacity 0.2s;
  opacity: 0;
}
Parameters
name type default description
name string mandatory The base string of the CSS class to be assigned. For example, if this string is "transition", the CSS class name would be "transition-enter", "transition-exit", etc.
options object | "size" | "details" | "dropdown" {} Specify options by object that extend the behavior of the CSS transitions.
You can also specify a string, in which case you specify the built-in behavior (called a "preset"). There are three presets: "size", "details" and "dropdown". See below.
options.target string ":scope" Specify a CSS selector for the DOM element to which the CSS class is to be assigned. The default is the DOM element itself that is under update monitoring.
The extraction of DOM elements by the selector starts from the DOM element that is the target of the update monitoring.
options.timeout number 10000 Specifies the time in milliseconds (1/1000 of a second) before the CSS transition is forced to end. Default is 10 seconds.
Normally, CSS transitions are terminated when the transitionend event is received. However, in case this does not happen for some reason, there is a force termination mechanism. You can specify here how many seconds to wait for the forced termination.
options.onstart function null A callback called just before starting a CSS transition. The parameters and return values of the callback are the same as those of the update monitoring.
options.onfinish function null A callback called just before the end of a CSS transition. The parameters and return values of the callback are the same as those of the update monitor.
Return Value
name type description
fn function Function that, when called, activates CSS transitions. Can be used as a callback for update monitoring.

How CSS transitions work

The CSS transition mechanism of batonjs is built in reference to React Transition Group.
The cssTransition function performs CSS class operations on DOM elements in the following steps. Define the appropriate CSS for each class so that the transition will be executed.

  1. Add transition-enter-before
    After this, the onstart callback is called.
  2. Remove transition-enter-before, Add transition-enter
    After this, a small amount of time is reserved to make the browser render the DOM element.
  3. Add transition-enter-active
    At this point, the CSS transition begins, and when the transitionend event is received, proceeds to the next step.
  4. Remove transition-enter-active and transition-enter
    After this, the onfinish callback is called.

You can use each class as follows.

In the transition-enter class, define the style at the start of the transition. In the case of a modal or other DOM element with a display property of none, this is where you change it to block.

In the transition-enter-active class, define the style for when the transition ends. In conjunction with the previous step, transition-enter-active is added after transition-enter. By adding the classes in this order, batonjs activates the CSS transition.
It is here that you define the transition property.

The transition-enter-before class is a class that is added in the preparatory stage before starting a transition. In some UIs, it is necessary to change the style for a moment before starting a transition, and then do some processing with that style. transition-enter-before is a class provided for such situations.

The class name given, such as "transition-enter", varies depending on the argument.
The "transition" part is the string passed as the first argument to the cssTransition function.
The "enter" part becomes "enter" when the third argument (newValue) of the update monitoring callback is true (truthy) and "exit" when it is false (falsy). For example, if the property to be monitored is open, "enter" will be given if the open property is true, and "exit" will be given if it is false.
Thus, the class name also changes depending on how the property value has changed, so that a different animation can be used for each.

size preset

The trouble with CSS transitions is when you want to change the height or width, because you have to measure the size of the DOM element in advance with javascript and then make the transition.

With the size preset, this can be automated.
The size preset will measure the size of the DOM element when it is displayed and set it to the style property as CSS custom properties.

The size preset defines following two CSS custom properties.

--width
Width of the target DOM element
--height
Height of the target DOM element

The size preset measures the size of the DOM element in the onstart callback. The user should ensure that the DOM element is visible when the onstart callback is called.
To do so, use the transition-enter-before class.

const transition = cssTransition("transition", "size")  // specifies size preset
const show = (state) => ({
  ".modal": {
    "class-is-open": state.modalIsOpen, 
    "&class-is-open": transition
  }
})
.modal.is-open, 
.modal.transition-enter-before {  /* We need this line to measure the size. */
  display: block;
  opacity: 1;
}
.modal.transition-enter {  /* on modal open */
  opacity: 0;
  height: 0;
  display: block;
}
.modal.transition-enter-active {
  transition: opacity 0.2s, height 0.2s;
  opacity: 1;
  height: var(--height);  /* using --height */
}
.modal.transition-exit {  /* on modal close */
  display: block;
  height: var(--height);  /* using --height */
}
.modal.transition-exit-active {
  transition: opacity 0.2s, height 0.2s;
  opacity: 0;
  height: 0;
}

details preset

The details preset is used to animate the opening and closing of details/summary element.
The element to be animated is the second child of the details element; since the first child is a summary, the second is the body part that will be invisible when closed.

The details preset defines custom properties by measuring the size of the body part, just like the size preset. Therefore, users of the details preset need to define CSS transitions for the body part.

An example of the use of the details preset can be found in Sample "jQuery's slideUp/Down".

A dropdown preset is a preset for defining a style of dropdown.
It will decide where to display the dropdown, measure the size, and set it to a custom property.

An example of the use of the dropdown preset can be found in Sample "Dropdown".