feat(esl-carousel): esl-carousel-autoplay plugin full support

Here is the full list of what new capabilities include:
 - Ability to pass multiple configuration.
 - Ability to control duration using time format.
 - Ability to pass selector for controls to toggle plugin state.
 - Ability to pass state marker classes to add to controls or/and container.
 - Dispatching of the state events.
 - Optional mixin/example - esl-carousel-autoplay-progress - to make simple autoplay progress UI
   (you can do progress controls based on CSS animation/transition out of the box without JS or use mixin source code as an example to crete custom control)

Author: ala-n

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

@@ -21,6 +21,8 @@ export * from './plugin/keyboard/esl-carousel.keyboard.mixin';
 
 // Autoplay
 export * from './plugin/autoplay/esl-carousel.autoplay.mixin';
+export * from './plugin/autoplay/esl-carousel.autoplay.event';
+export * from './plugin/autoplay/esl-carousel.autoplay.progress.mixin';
 
 // Link Utility
 export * from './plugin/relation/esl-carousel.relation.mixin';

packages/esl/src/esl-carousel/plugin/autoplay/esl-carousel.autoplay.event.ts

@@ -0,0 +1,36 @@
+import type {ESLCarousel} from '../../core/esl-carousel';
+import type {ESLCarouselAutoplayMixin} from './esl-carousel.autoplay.mixin';
+
+interface ESLCarouselAutoplayEventInit {
+  /** Whether autoplay plugin is enabled or disabled */
+  enabled: boolean;
+  /** Whether autoplay cycle is currently active */
+  active: boolean;
+  /** Duration of the current autoplay cycle in milliseconds */
+  duration: number;
+}
+/**
+ * ESLCarouselAutoplayEvent (esl:autoplay:change) event is dispatched by {@link ESLCarouselAutoplayMixin}
+ * on the host {@link ESLCarousel} element when autoplay state changes.
+ * It indicates whether autoplay is enabled or disabled, or notifies about the current autoplay cycle start.
+ */
+export class ESLCarouselAutoplayEvent extends Event implements ESLCarouselAutoplayEventInit {
+  public static readonly NAME = 'esl:autoplay:change';
+
+  public override target: ESLCarousel;
+
+  public readonly enabled: boolean;
+  public readonly active: boolean;
+  public readonly duration: number;
+
+  protected constructor(init: ESLCarouselAutoplayEventInit) {
+    super(ESLCarouselAutoplayEvent.NAME, {bubbles: false, cancelable: false});
+    Object.assign(this, init);
+  }
+
+  public static dispatch(plugin: ESLCarouselAutoplayMixin): boolean {
+    const {enabled, active, duration} = plugin;
+    const event = new ESLCarouselAutoplayEvent({enabled, active, duration});
+    return plugin.$host.dispatchEvent(event);
+  }
+}

packages/esl/src/esl-carousel/plugin/autoplay/esl-carousel.autoplay.mixin.ts

@@ -1,15 +1,24 @@
 import {ExportNs} from '../../../esl-utils/environment/export-ns';
-import {bind, listen, memoize, ready} from '../../../esl-utils/decorators';
+import {listen, memoize, ready} from '../../../esl-utils/decorators';
+import {parseTime} from '../../../esl-utils/misc/format';
+import {CSSClassUtils} from '../../../esl-utils/dom/class';
+import {ESLTraversingQuery} from '../../../esl-traversing-query/core';
 
 import {ESLCarouselPlugin} from '../esl-carousel.plugin';
 import {ESLCarouselSlideEvent} from '../../core/esl-carousel.events';
-import {parseTime} from '../../../esl-utils/misc/format';
+import {ESLCarouselAutoplayEvent} from './esl-carousel.autoplay.event';
 
 export interface ESLCarouselAutoplayConfig {
   /** Timeout to send next command to the host carousel */
-  timeout: string | number;
+  duration: string | number;
   /** Navigation command to send to the host carousel. Default: 'slide:next' */
   command: string;
+  /** Selector for control to toggle plugin state */
+  control?: string;
+  /** Class to toggle on control element, when autoplay is active */
+  controlCls?: string;
+  /** Class to toggle on container element, when autoplay is active */
+  containerCls?: string;
 }
 
 /**
@@ -22,68 +31,122 @@ export interface ESLCarouselAutoplayConfig {
 export class ESLCarouselAutoplayMixin extends ESLCarouselPlugin<ESLCarouselAutoplayConfig> {
   public static override is = 'esl-carousel-autoplay';
   public static override DEFAULT_CONFIG: ESLCarouselAutoplayConfig = {
-    timeout: 5000,
+    duration: 5000,
     command: 'slide:next'
   };
-  public static override DEFAULT_CONFIG_KEY = 'timeout';
+  public static override DEFAULT_CONFIG_KEY: keyof ESLCarouselAutoplayConfig = 'duration';
 
-  private _timeout: number | null = null;
+  private _enabled: boolean = true;
+  private _duration: number | null = null;
 
+  /** True if the autoplay timer is currently active */
   public get active(): boolean {
-    return !!this._timeout;
+    return !!this._duration;
   }
-  public get timeout(): number {
-    return parseTime(this.config.timeout);
+
+  /** True if the autoplay plugin is enabled */
+  public get enabled(): boolean {
+    return this._enabled;
+  }
+  protected set enabled(value: boolean) {
+    this._enabled = value;
+    CSSClassUtils.toggle(this.$controls, this.config.controlCls, this._enabled);
+    const {$container} = this.$host;
+    $container && CSSClassUtils.toggle($container, this.config.containerCls, this._enabled);
+  }
+
+  /** The duration of the autoplay timer in milliseconds */
+  public get duration(): number {
+    return parseTime(this.config.duration);
+  }
+
+  /** A list of control elements to toggle plugin state */
+  @memoize()
+  public get $controls(): HTMLElement[] {
+    const sel = this.config.control;
+    return sel ? ESLTraversingQuery.all(sel, this.$host) as HTMLElement[] : [];
   }
 
   @ready
   protected override connectedCallback(): void {
-    if (super.connectedCallback()) {
-      this.start();
-    }
+    super.connectedCallback();
+    this.start();
   }
 
   protected override disconnectedCallback(): void {
     super.disconnectedCallback();
     this.stop();
   }
 
+  @listen({inherit: true})
   protected override onConfigChange(): void {
+    super.onConfigChange();
+    memoize.clear(this, ['$controls', 'duration']);
+    // Full restart during config change
+    this.stop();
     this.start();
   }
 
-  /** Activates the timer to send commands */
+  /** Activates and restarts the autoplay carousel timer */
   public start(): void {
-    this.stop();
-    const {timeout} = this;
-    if (timeout <= 0 || isNaN(+timeout)) return;
-    this._timeout = window.setTimeout(this._onInterval, timeout);
+    const {duration} = this;
+    this.enabled = +duration > 0;
+    if (this.enabled) this._onCycle();
   }
 
-  /** Deactivates the timer to send commands */
-  public stop(): void {
-    this._timeout && window.clearTimeout(this._timeout);
-    this._timeout = null;
+  /**
+   * Deactivates the autoplay carousel timer.
+   * @param system - If true, the plugin will be suspended but not disabled.
+   */
+  public stop(system = false): void {
+    if (!this.active && !this.enabled) return;
+    if (!system) this.enabled = false;
+    this._duration && window.clearTimeout(this._duration);
+    this._duration = null;
+    ESLCarouselAutoplayEvent.dispatch(this);
   }
 
-  /** Handles next timer interval */
-  @bind
-  protected _onInterval(): void {
-    this.$host?.goTo(this.config.command);
-    this._timeout = window.setTimeout(this._onInterval, this.timeout);
+  /**
+   * Starts a new autoplay cycle.
+   * Produces cycle self call after a timeout with enabled command execution.
+   */
+  protected async _onCycle(exec?: boolean): Promise<void> {
+    this._duration && window.clearTimeout(this._duration);
+    this._duration = null;
+    if (exec) await this.$host?.goTo(this.config.command);
+    if (!this.enabled || this.active) return;
+    const {duration} = this;
+    this._duration = window.setTimeout(() => this._onCycle(true), duration);
+    ESLCarouselAutoplayEvent.dispatch(this);
   }
 
-  /** Handles auxiliary events to pause/resume timer */
-  @listen(`mouseout mouseover focusin focusout ${ESLCarouselSlideEvent.AFTER}`)
+  /** Handles click on control element to toggle plugin state */
+  @listen({
+    event: 'click',
+    target: ($this: ESLCarouselAutoplayMixin)=> $this.$controls,
+    condition: ($this: ESLCarouselAutoplayMixin)=> !!$this.$controls.length
+  })
+  protected _onToggle(e: Event): void {
+    this.enabled ? this.stop() : this.start();
+    e.preventDefault();
+  }
+
+  /** Handles auxiliary events that represent user interaction to pause/resume timer */
+  @listen('mouseleave mouseenter focusin focusout')
   protected _onInteract(e: Event): void {
-    // Slide change can only delay the timer, but not start it
-    if (e.type === ESLCarouselSlideEvent.AFTER && !this.active) return;
-    if (['mouseover', 'focusin'].includes(e.type)) {
-      this.stop();
+    if (!this.enabled) return;
+    if (['mouseenter', 'focusin'].includes(e.type)) {
+      this.stop(true);
     } else {
       this.start();
     }
   }
+
+  /** Handles carousel slide change event to restart the timer */
+  @listen(ESLCarouselSlideEvent.AFTER)
+  protected _onSlideChange(): void {
+    if (this.active) this.start();
+  }
 }
 
 declare global {

packages/esl/src/esl-carousel/plugin/autoplay/esl-carousel.autoplay.progress.mixin.ts

@@ -0,0 +1,48 @@
+import {ESLMixinElement} from '../../../esl-mixin-element/core';
+import {attr, boolAttr, listen} from '../../../esl-utils/decorators';
+import {afterNextRender} from '../../../esl-utils/async/raf';
+import {ESLCarouselAutoplayEvent} from './esl-carousel.autoplay.event';
+
+/**
+ * A mixin (custom attribute) element that manages the progress animation for the autoplay functionality
+ * of an ESL Carousel. It listens for `ESLCarouselAutoplayEvent` events and updates
+ * the animation state and autoplay status accordingly.
+ * Uses three markers to represent the autoplay progress:
+ * - `animate` attribute - appears on each cycle of active autoplay;
+ * drops one frame before the next cycle to activate CSS animation
+ * - `autoplay-enabled` attribute - indicates whether the autoplay plugin is enabled
+ * - `--esl-autoplay-timeout` CSS variable - indicates the current autoplay cycle duration
+ */
+export class ESLCarouselAutoplayProgressMixin extends ESLMixinElement {
+  public static override is = 'esl-carousel-autoplay-progress';
+
+  /**
+   * {@link ESLTraversingQuery} string to find {@link ESLCarousel} instance with autoplay plugin.
+   * Searching for the carousel in bounds of the `.esl-carousel-nav-container` element by default.
+   */
+  @attr({
+    name: 'target',
+    defaultValue: '::parent(.esl-carousel-nav-container)::find(esl-carousel)'
+  })
+  public carousel: string;
+
+  /** Attribute to start animation representing autoplay cycle */
+  @boolAttr() public animate: boolean;
+  /** Autoplay enabled status marker attribute */
+  @boolAttr() public autoplayEnabled: boolean;
+
+  protected override attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void {
+    this.$$on(this._onChange);
+  }
+
+  @listen({
+    event: ESLCarouselAutoplayEvent.NAME,
+    target: ($this: ESLCarouselAutoplayProgressMixin) => $this.carousel
+  })
+  protected _onChange(e: ESLCarouselAutoplayEvent): void {
+    this.autoplayEnabled = e.enabled;
+    this.$host.style.setProperty('--esl-autoplay-timeout', `${e.duration}ms`);
+    requestAnimationFrame(() => this.animate = false);
+    e.active && afterNextRender(() => this.animate = true);
+  }
+}