Merge pull request #3106 from exadel-inc/feat/esl-carousel-css

epic: CSS Based ESLCarousel renderers

Author: ala-n

packages/esl-website/views/examples/carousel/css-fade.sample.njk

@@ -0,0 +1,47 @@
+---
+title: Fade Carousel (CSS)
+order: -1
+tags: carousel-sample
+---
+
+<div class="esl-carousel-no-extra-space esl-carousel-nav-container">
+  <button type="button" class="esl-carousel-arrow inner prev hide-xs" esl-carousel-nav="group:prev">
+    <span class="sr-only">Previous Slide</span>
+  </button>
+
+  <esl-carousel demo-options-target
+                type="css-fade"
+                esl-carousel-touch=""
+                loop="true">
+    <ul esl-carousel-slides>
+      {% for i in range(0, 4) -%}
+        <li esl-carousel-slide {{ 'active' if loop.first }}>
+          <div class="card">
+            <div class="img-container img-container-16-9" esl-image-container>
+              <img class="img-fade img-cover"
+                   alt="{{ 'Carousel slide ' + loop.index }}"
+                   src="{{ '/assets/carousel/' + loop.index + '-sm.jpg' | url }}"
+                   loading="lazy" />
+              <div class="h1 text-slide text-white">Slide {{ loop.index }}</div>
+            </div>
+          </div>
+        </li>
+      {%- endfor %}
+    </ul>
+  </esl-carousel>
+
+  <button type="button" class="esl-carousel-arrow inner next hide-xs" esl-carousel-nav="group:next">
+    <span class="sr-only">Next Slide</span>
+  </button>
+
+  <esl-carousel-dots class="carousel-dots-wrapper"></esl-carousel-dots>
+
+  <style>
+    .text-slide {
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      transform: translate(-50%, -50%);
+    }
+  </style>
+</div>

packages/esl/src/esl-carousel/README.md

@@ -185,7 +185,10 @@ To fine-tune the layout you can use the following recipes:
     To define the space between the slides you can just use native flexbox `gap` property.
     The renderer is aware of the gap and will adjust the slide size and calculations accordingly.
   3. Transitions:
-    The renderer utilizes JS Animation API to animate the slides. The only way to customize the transition timing is to use the `step-duration` attribute on the `esl-carousel` element.
+     The renderer uses the JavaScript Animation API to animate slides. The only way to customize the transition is by setting the duration via the CSS variable `--esl-carousel-step-duration`. 
+     The carousel renderer reads the computed value of this CSS variable to determine the transition duration.
+     In addition to using the CSS variable directly, you can also specify the `step-duration` attribute on the `<esl-carousel>` element. This attribute supports `ESLMediaRuleList` syntax, including definitions based on `media` attribute. 
+     Technically, the `step-duration` attribute sets the transition duration CSS variable on the carousel root element during the animation step.
   4. Siblings visibility and overflow:
     The CSS overflow property is set to `clip`(or `hidden` for legacy browsers) on the `esl-carousel` element to hide out of view slides.
     However, the start position and calculations are based on `esl-carousel-slides` container element.
@@ -197,12 +200,42 @@ To fine-tune the layout you can use the following recipes:
     Note that if you use siblings visibility effect, you will not see the last slide before the first one in the loop mode unless backward animation is playing.
     However, this option could be useful to limit CLS issues, when content of the slide is heavy (e.g. `esl-media` with the fill option).
 
+- #### Centered (type: `centered`) Renderer
+An extension of the default renderer that centers the active slide in the carousel.
+Does not have any critical configurational or functional differences from the default renderer except the process of offset calculation.
+
 - #### Grid (type: `grid`) Renderer <i class="badge badge-sup badge-warning">beta</i>
 The grid renderer for ESL Carousel is based on the Default renderer but uses the CSS Grid layout to display slides.
 Unlike the Default renderer, the Grid renderer displays multiple rows (horizontal case) or columns (vertical case) of slides.
 
 Note that the Grid renderer is more restrictive in terms of the slide size definition. Unlike the Default renderer, the Grid renderer does not support relative sizes for the slides (grid layout liitations).
 
+#### Default CSS Renderer (type: `css`)
+Uses the `ESLCSSCarouselRenderer` implementation.
+This renderer does not apply any JavaScript-based animation logic. It relies entirely on CSS-defined transitions and animations.
+
+> **Note:** This renderer does not listen for specific transition or animation events. Therefore, the animation duration must be explicitly defined using the `--esl-carousel-step-duration` CSS variable.
+It is also good practice to use the `--esl-carousel-step-duration` CSS variable within your animation. This enables duration customization via the `step-duration` attribute as well.
+
+Animations can make use of global markers such as `active`, `pre-active`, `next`, and `prev` attributes, as well as the `animating` state attribute on the carousel element.
+
+Additionally, the renderer provides the CSS classes `left`, `right`, `forward`, and `backward` on affected slides to help define animation direction.
+
+The renderer supports the move operation, but you must rely on one of the following CSS variables and markers:
+* `shifted` – A root element attribute added to the carousel element when the move operation is not committed.
+* `--esl-carousel-offset` – A CSS variable representing the move offset in pixels.
+* `--esl-carousel-offset-ratio` – A CSS variable representing the offset relative to the carousel size and move tolerance.
+
+By default, this renderer does not include any specific animation. However, several built-in animation implementations are provided (detailed below).
+
+#### CSS Fade Renderer (type: `css-fade`)
+An extension of the default CSS renderer that provides fade animation styles for slide transitions.
+Supports move operations relative to the carousel size and move tolerance.
+
+#### CSS Slide Renderer (type: `css-slide`)
+An extension of the default CSS renderer that provides sliding animation styles for slide transitions.
+Supports move operations based on absolute pixel offset.
+
 - #### None (type: `none`) Renderer
 The none renderer for ESL Carousel is a dummy renderer that does not change the slides layout and assumes that all the slides are visible at once.
 It is useful when you want to 'mute' the carousel behavior for some media conditions. 

packages/esl/src/esl-carousel/core.less

@@ -3,3 +3,6 @@
 // Renderer Default
 @import './renderers/esl-carousel.default.renderer.less';
 @import './renderers/esl-carousel.grid.renderer.less';
+@import './renderers/esl-carousel.css.renderer.less';
+@import './renderers/esl-carousel.css.fade.renderer.less';
+@import './renderers/esl-carousel.css.slide.renderer.less';

packages/esl/src/esl-carousel/core.ts

@@ -33,3 +33,6 @@ import './renderers/esl-carousel.none.renderer';
 import './renderers/esl-carousel.default.renderer';
 import './renderers/esl-carousel.grid.renderer';
 import './renderers/esl-carousel.centered.renderer';
+import './renderers/esl-carousel.css.renderer';
+import './renderers/esl-carousel.css.fade.renderer';
+import './renderers/esl-carousel.css.slide.renderer';

packages/esl/src/esl-carousel/core/esl-carousel.less

@@ -1,6 +1,7 @@
 :root {
   --esl-slide-initial-size: 100%;
   --esl-carousel-side-space: 5px;
+  --esl-carousel-step-duration: 250ms;
 }
 
 // CORE styles

packages/esl/src/esl-carousel/core/esl-carousel.renderer.ts

@@ -1,5 +1,7 @@
 import {memoize} from '../../esl-utils/decorators';
 import {isEqual} from '../../esl-utils/misc/object';
+import {parseTime} from '../../esl-utils/misc/format';
+import {promisifyTimeout} from '../../esl-utils/async/promise/timeout';
 import {SyntheticEventTarget} from '../../esl-utils/dom';
 import {ESLCarouselDirection} from './esl-carousel.types';
 import {ESLCarouselSlideEvent} from './esl-carousel.events';
@@ -10,6 +12,9 @@ import type {ESLCarouselSlideEventInit} from './esl-carousel.events';
 import type {ESLCarouselActionParams, ESLCarouselConfig, ESLCarouselNavInfo} from './esl-carousel.types';
 
 export abstract class ESLCarouselRenderer implements ESLCarouselConfig {
+  /** CSS variable name to set transition duration */
+  public static readonly TRANSITION_DURATION_PROP = '--esl-carousel-step-duration';
+
   public static is: string;
   public static classes: string[] = [];
 
@@ -63,6 +68,29 @@ export abstract class ESLCarouselRenderer implements ESLCarouselConfig {
     return this.$carousel.$slides || [];
   }
 
+  protected get animating(): boolean {
+    return this.$carousel.hasAttribute('animating');
+  }
+  protected set animating(value: boolean) {
+    this.$carousel.toggleAttribute('animating', value);
+  }
+
+  protected get transitionDuration(): number {
+    const name = ESLCarouselRenderer.TRANSITION_DURATION_PROP;
+    const duration = getComputedStyle(this.$area).getPropertyValue(name);
+    return parseTime(duration);
+  }
+  protected set transitionDuration(value: number | null) {
+    if (typeof value === 'number' && value > 0) {
+      this.$carousel.style.setProperty(ESLCarouselRenderer.TRANSITION_DURATION_PROP, `${value}ms`);
+    } else {
+      this.$carousel.style.removeProperty(ESLCarouselRenderer.TRANSITION_DURATION_PROP);
+    }
+  }
+  protected get transitionDuration$$(): Promise<void> {
+    return promisifyTimeout(this.transitionDuration);
+  }
+
   public equal(config: ESLCarouselConfig): boolean {
     return isEqual(this.config, config);
   }
@@ -117,13 +145,15 @@ export abstract class ESLCarouselRenderer implements ESLCarouselConfig {
     this.$carousel.dispatchEvent(ESLCarouselSlideEvent.create('CHANGE', details));
     this.setPreActive(index);
 
+    this.transitionDuration = params.stepDuration;
     try {
       await this.onBeforeAnimate(index, direction, params);
       await this.onAnimate(index, direction, params);
       await this.onAfterAnimate(index, direction, params);
     } catch (e: unknown) {
       console.error(e);
     }
+    this.transitionDuration = null;
 
     this.setActive(index, {direction, ...params});
   }

packages/esl/src/esl-carousel/core/esl-carousel.ts

@@ -3,7 +3,7 @@ import {ESLBaseElement} from '../../esl-base-element/core';
 import {attr, boolAttr, ready, decorate, listen, memoize} from '../../esl-utils/decorators';
 import {isMatches} from '../../esl-utils/dom/traversing';
 import {microtask} from '../../esl-utils/async';
-import {parseBoolean, parseTime, sequentialUID} from '../../esl-utils/misc';
+import {parseBoolean, parseTime, sequentialUID, toCamelCase} from '../../esl-utils/misc';
 
 import {CSSClassUtils} from '../../esl-utils/dom/class';
 import {ESLTraversingQuery} from '../../esl-traversing-query/core';
@@ -47,7 +47,7 @@ export class ESLCarousel extends ESLBaseElement {
   @attr({defaultValue: 'false'}) public vertical: string | boolean;
 
   /** Duration of the single slide transition */
-  @attr({defaultValue: '250'}) public stepDuration: string;
+  @attr() public stepDuration: string;
 
   /** Container selector (supports traversing query). Carousel itself by default */
   @attr({defaultValue: ''}) public container: string;
@@ -143,7 +143,7 @@ export class ESLCarousel extends ESLBaseElement {
       memoize.clear(this, '$container');
       return this.updateStateMarkers();
     }
-    memoize.clear(this, `${attrName}Rule`);
+    memoize.clear(this, `${toCamelCase(attrName)}Rule`);
     this.update();
   }
 

packages/esl/src/esl-carousel/renderers/esl-carousel.css.fade.renderer.less

@@ -0,0 +1,26 @@
+.esl-carousel-css-renderer.esl-carousel-css-fade {
+  &[animating] [esl-carousel-slide] {
+    transition: opacity var(--esl-carousel-step-duration) linear;
+  }
+
+  [esl-carousel-slide] {
+    opacity: 0;
+  }
+  [esl-carousel-slide][active] {
+    opacity: 1;
+  }
+  [esl-carousel-slide][pre-active] {
+    position: absolute;
+    top: 0;
+    width: 100%;
+  }
+  &[animating] [esl-carousel-slide][pre-active] {
+    z-index: 2;
+    opacity: 1;
+  }
+
+  &[shifted] [esl-carousel-slide][pre-active] {
+    z-index: 2;
+    opacity: var(--esl-carousel-offset-ratio, 0);
+  }
+}

packages/esl/src/esl-carousel/renderers/esl-carousel.css.fade.renderer.ts

@@ -0,0 +1,11 @@
+import {ESLCarouselRenderer} from '../core/esl-carousel.renderer';
+import {ESLCSSCarouselRenderer} from './esl-carousel.css.renderer';
+
+@ESLCarouselRenderer.register
+export class ESLCSSFadeCarouselRenderer extends ESLCSSCarouselRenderer {
+  public static override is = 'css-fade';
+  public static override classes: string[] = [
+    ...ESLCSSCarouselRenderer.classes,
+    'esl-carousel-css-fade'
+  ];
+}

packages/esl/src/esl-carousel/renderers/esl-carousel.css.renderer.less

@@ -0,0 +1,18 @@
+.esl-carousel-css-renderer {
+  [esl-carousel-slides] {
+    display: block;
+    position: relative;
+    width: 100%;
+  }
+
+  [esl-carousel-slide] {
+    position: relative;
+    display: none;
+    backface-visibility: hidden;
+  }
+
+  [esl-carousel-slide][active],
+  [esl-carousel-slide][pre-active] {
+    display: block;
+  }
+}