feat(esl-carousel): support for proactive container-class handling using 'esl-carousel-class-behavior' plugin

Author: ala-n

packages/esl-website/src/site.ts

@@ -40,6 +40,7 @@ import {
   ESLCarouselRelateToMixin,
   ESLCarouselAutoplayMixin,
   ESLCarouselAutoplayProgressMixin,
+  ESLCarouselClassBehaviourMixin,
   ESLLazyTemplate
 } from '@exadel/esl/modules/all';
 
@@ -128,6 +129,7 @@ ESLCarouselRelateToMixin.register();
 ESLCarouselAutoplayMixin.register();
 ESLCarouselAutoplayProgressMixin.register();
 ESLCarouselWheelMixin.register();
+ESLCarouselClassBehaviourMixin.register();
 
 ESLAnimate.register();
 ESLAnimateMixin.register();

packages/esl-website/views/components/esl-carousel/container-class.njk

@@ -0,0 +1,15 @@
+---
+layout: content
+title: ESL Carousel Container Class Behavior
+seoTitle: ESL Carousel Container Class Behavior - part of ESL Carousel web component to customize carousel container class behavior
+name: Container Class Behavior
+order: 2
+parent: 'ESL Carousel'
+tags: [components, new, beta]
+aside:
+  source: packages/esl/src/esl-carousel
+  examples:
+    - carousel
+---
+
+{% mdRender '@exadel/esl/modules/esl-carousel/plugin/class/README.md', 'intro' %}

packages/esl-website/views/components/esl-carousel/keyboard.njk

@@ -4,8 +4,8 @@ title: ESL Carousel Keyboard
 seoTitle: ESL Carousel Keyboard - part of ESL Carousel web component to create carousel UX with custom plugins, rendering and out of the box popular features support
 name: Keyboard Navigation
 parent: 'ESL Carousel'
-order: 3
-tags: [components, draft]
+order: 5
+tags: [components]
 aside:
   source: packages/esl/src/esl-carousel
   examples:

packages/esl-website/views/components/esl-carousel/relation.njk

@@ -4,7 +4,7 @@ title: ESL Carousel Relation
 seoTitle: ESL Carousel Relation - part of ESL Carousel web component to create carousel UX with custom plugins, rendering and out of the box popular features support
 name: Linking Carousels
 parent: 'ESL Carousel'
-order: 5
+order: 7
 tags: [components, draft]
 aside:
   source: packages/esl/src/esl-carousel

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

@@ -30,6 +30,9 @@ export * from './plugin/relation/esl-carousel.relation.mixin';
 // Wheel support
 export * from './plugin/wheel/esl-carousel.wheel.mixin';
 
+// Class management
+export * from './plugin/class/esl-carousel.class-behaviour.mixin';
+
 // Renderer Default
 import './renderers/esl-carousel.none.renderer';
 import './renderers/esl-carousel.default.renderer';

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

@@ -0,0 +1,49 @@
+# ESL Carousel Container Class Plugin <i class="badge badge-sup badge-warning">beta</i>
+
+<a name="intro"></a>
+
+The `esl-carousel-class-behavior` is a plugin (mixin) for `ESLCarousel` that provides advanced control over the `container-class` feature. 
+By default, the `container-class` attribute works out-of-the-box in `default` mode, where classes are updated on the container after the slide change. 
+The plugin enables a `proactive` mode, where classes are updated as soon as the slide change starts, which can be useful for certain animation types.
+
+**Note:** The plugin is currently in beta and only supports the `mode` configuration.
+
+## Configuration
+The `esl-carousel-class-behavior` plugin uses the ESLMediaQuery syntax for configuration. 
+The only supported configuration option is `mode`, which can be set to either `default` or `proactive`.
+- `default`: The container's classes are updated after the slide change completes. THis is the default ESLCarousel behavior, the plugin is not needed if you use only this mode.
+- `proactive`: The container's classes are updated as soon as the slide change starts, before the transition begins. This mode is useful for animations that require the container class to be updated immediately.
+
+NOTE: As was previously mentioned, the plugin value supports the ESLMediaQuery syntax, which allows you to switch between different modes based on animation and renderer you use.
+
+NOTE: Plugin does not change target for the `container-class` attribute, so if behaves exactly like ESLCarousel's API defines it (based on `container` attribute).
+
+## Usage
+To use the mixin, register the `ESLCarouselContainerClassMixin`:
+
+```javascript
+EslCarouselClassBehaviourMixin.register();
+```
+
+Then use the mixin on any `esl-carousel` element where you want to control container classes:
+```html
+<esl-carousel esl-carousel-class-behavior="proactive">
+  <ul esl-carousel-slides>
+    <li esl-carousel-slide container-class="my-slide-class-1">Slide 1</li>
+    <li esl-carousel-slide container-class="my-slide-class-2">Slide 2</li>
+  </ul>
+</esl-carousel>
+```
+
+To use different modes for different renderers/media conditions:
+```html
+<esl-carousel media="@XS|@+SM" type="css-slide|css-fade" esl-carousel-class-behavior="default|proactive">
+  ...
+</esl-carousel>
+```
+or
+```html
+<esl-carousel media="@XS|@+SM" type="css-slide|css-fade" esl-carousel-class-behavior="default | @+SM => proactive">
+  ...
+</esl-carousel>
+```

packages/esl/src/esl-carousel/plugin/class/esl-carousel.class-behaviour.mixin.ts

@@ -0,0 +1,50 @@
+import {ESLCarouselPlugin} from '../esl-carousel.plugin';
+import {listen} from '../../../esl-utils/decorators/listen';
+import {CSSClassUtils} from '../../../esl-utils/dom/class';
+import {ESLCarouselSlide} from '../../core/esl-carousel.slide';
+import {ESLCarouselSlideEvent} from '../../core/esl-carousel.events';
+
+export interface ESLCarouselClassBehaviourConfig {
+  mode?: 'default' | 'proactive';
+}
+
+/**
+ * Plugin for {@link ESLCarousel} that allows to control the `container-class` feature behavior.
+ *
+ * Supports two modes:
+ * - `default`: do not change default behavior - adds/removes classes on the container element after slides changed
+ * - `proactive`: adds/removes classes on the container element proactively as soon as change starts
+ */
+export class ESLCarouselClassBehaviourMixin extends ESLCarouselPlugin<ESLCarouselClassBehaviourConfig> {
+  public static override is = 'esl-carousel-class-behavior';
+  public static override DEFAULT_CONFIG: ESLCarouselClassBehaviourConfig = {
+    mode: 'default'
+  };
+  public static override DEFAULT_CONFIG_KEY: keyof ESLCarouselClassBehaviourConfig = 'mode';
+
+  @listen({inherit: true})
+  protected override onConfigChange(): void {
+    super.onConfigChange();
+    this.$$on(this.onSlideChange);
+  }
+
+  /** Resolves the container classes from given slide element */
+  protected getClasses($slide: HTMLElement): string | undefined {
+    return ESLCarouselSlide.get($slide)?.containerClass;
+  }
+
+  @listen({
+    event: ESLCarouselSlideEvent.CHANGE,
+    condition: ($this: ESLCarouselClassBehaviourMixin) => $this.config.mode === 'proactive',
+  })
+  protected onSlideChange({$slidesBefore, $slidesAfter}: ESLCarouselSlideEvent): void {
+    const {$container} = this.$host;
+    if (!$container) return;
+    for (const $slide of $slidesBefore) {
+      CSSClassUtils.remove($container, this.getClasses($slide), $slide);
+    }
+    for (const $slide of $slidesAfter) {
+      CSSClassUtils.add($container, this.getClasses($slide), $slide);
+    }
+  }
+}