Merge branch 'master' into didimmova/update-textarea-theme

Author: simeonoff

ROADMAP.md

@@ -2,19 +2,29 @@
 
 # Current Milestone
 
-## Milestone 17 (Due Jun, 2025)
+## Milestone 20 (Due Nov, 2025)
 
-1. Date range picker [1596](https://github.com/IgniteUI/igniteui-webcomponents/issues/1596)
-2. Tooltip component [1615](https://github.com/IgniteUI/igniteui-webcomponents/issues/1615)
+1. Grids Cell Merging feature
+2. Grids Pining on both sides feature
 
 ## Going down the road
 
-1. Bottom navigation component [#169](https://github.com/IgniteUI/igniteui-webcomponents/issues/169)
-2. Splitter component [#184](https://github.com/IgniteUI/igniteui-webcomponents/issues/184)
-3. Chat UI component
+1. Grids localization 
 
 # Previous Milestone
 
+## Milestone 19, version 6.3.0, Released Sep 18th, 2025
+
+1. **[DONE]** Chat component
+
+## Milestone 18, version 6.1.0, Released Jun 12th, 2025
+
+1. **[DONE]** Date range picker [1596](https://github.com/IgniteUI/igniteui-webcomponents/issues/1596)
+
+## Milestone 17, version 5.4.0, Released Apr 23rd, 2025
+
+1. **[DONE]** Tooltip component [1615](https://github.com/IgniteUI/igniteui-webcomponents/issues/1615)
+   
 ## Milestone 16, version 5.3.0, Released Mar 13th, 2025
 
 1. **[DONE]** Tile manager component [#1402](https://github.com/IgniteUI/igniteui-webcomponents/pull/1402) 

src/animations/player.spec.ts

@@ -63,7 +63,7 @@ describe('Animations Player', () => {
   it('should cancel running animations', async () => {
     const [playbackEvent] = (await Promise.all([
       el.player.play(fade),
-      el.player.stopAll(),
+      el.player.cancelAll(),
     ])) as AnimationPlaybackEvent[];
 
     expect(playbackEvent.type).to.equal('cancel');

src/animations/player.ts

@@ -1,86 +1,113 @@
 import type { ReactiveController, ReactiveControllerHost } from 'lit';
 import type { Ref } from 'lit/directives/ref.js';
-
 import { isElement } from '../components/common/util.js';
 import type { AnimationReferenceMetadata } from './types.js';
 
-const listenerOptions = { once: true };
+/**
+ * Defines the result of an optional View Transition start.
+ */
+type ViewTransitionResult = {
+  transition?: ViewTransition;
+};
+
+const LISTENER_OPTIONS = { once: true } as const;
 
-function getPrefersReducedMotion() {
+/**
+ * Checks the user's preference for reduced motion.
+ */
+function getPrefersReducedMotion(): boolean {
   return globalThis?.matchMedia('(prefers-reduced-motion: reduce)').matches;
 }
 
+/**
+ * A ReactiveController for managing Web Animation API (WAAPI) playback
+ * on a host element or a specified target element.
+ *
+ * It provides methods to play, stop, and coordinate animations, including
+ * support for 'height: auto' transitions and reduced motion preference.
+ */
 class AnimationController implements ReactiveController {
-  protected get target() {
-    if (isElement(this._target)) {
-      return this._target;
+  private readonly _host: ReactiveControllerHost & HTMLElement;
+  private readonly _ref?: Ref<HTMLElement> | HTMLElement;
+
+  /**
+   * The actual HTMLElement target for the animations.
+   * Prioritizes a passed-in Ref value, then a direct HTMLElement, falling back to the host.
+   */
+  protected get _target(): HTMLElement {
+    if (isElement(this._ref)) {
+      return this._ref;
     }
-    return this._target?.value ?? this.host;
+
+    return this._ref?.value ?? this._host;
   }
 
   constructor(
-    private readonly host: ReactiveControllerHost & HTMLElement,
-    private _target?: Ref<HTMLElement> | HTMLElement
+    host: ReactiveControllerHost & HTMLElement,
+    ref?: Ref<HTMLElement> | HTMLElement
   ) {
-    this.host.addController(this);
+    this._host = host;
+    this._ref = ref;
+    this._host.addController(this);
   }
 
-  private parseKeyframes(keyframes: Keyframe[]) {
-    return keyframes.map((keyframe) => {
-      if (!keyframe.height) return keyframe;
-
-      return {
-        ...keyframe,
-        height:
-          keyframe.height === 'auto'
-            ? `${this.target.scrollHeight}px`
-            : keyframe.height,
-      };
+  /** Pre-processes keyframes, specifically resolving 'auto' height to the element's scrollHeight. */
+  private _parseKeyframes(keyframes: Keyframe[]): Keyframe[] {
+    const target = this._target;
+
+    return keyframes.map((frame) => {
+      return frame.height === 'auto'
+        ? { ...frame, height: `${target.scrollHeight}px` }
+        : frame;
     });
   }
 
-  public async play(animation: AnimationReferenceMetadata) {
+  /** @internal */
+  public hostConnected(): void {}
+
+  /** Plays a sequence of keyframes, first cancelling all existing animations on the target. */
+  public async playExclusive(
+    animation: AnimationReferenceMetadata
+  ): Promise<boolean> {
+    await this.cancelAll();
+
+    const event = await this.play(animation);
+    return event.type === 'finish';
+  }
+
+  /**
+   * Plays a sequence of keyframes using WAAPI.
+   * Automatically sets duration to 0 if 'prefers-reduced-motion' is set.
+   */
+  public async play(
+    animation: AnimationReferenceMetadata
+  ): Promise<AnimationPlaybackEvent> {
     const { steps, options } = animation;
+    const duration = getPrefersReducedMotion() ? 0 : (options?.duration ?? 0);
 
-    if (options?.duration === Number.POSITIVE_INFINITY) {
+    if (!Number.isFinite(duration)) {
       throw new Error('Promise-based animations must be finite.');
     }
 
     return new Promise<AnimationPlaybackEvent>((resolve) => {
-      const animation = this.target.animate(this.parseKeyframes(steps), {
+      const animation = this._target.animate(this._parseKeyframes(steps), {
         ...options,
-        duration: getPrefersReducedMotion() ? 0 : options!.duration,
+        duration,
       });
 
-      animation.addEventListener('cancel', resolve, listenerOptions);
-      animation.addEventListener('finish', resolve, listenerOptions);
+      animation.addEventListener('cancel', resolve, LISTENER_OPTIONS);
+      animation.addEventListener('finish', resolve, LISTENER_OPTIONS);
     });
   }
 
-  public stopAll() {
-    return Promise.all(
-      this.target.getAnimations().map((animation) => {
-        return new Promise((resolve) => {
-          const resolver = () => requestAnimationFrame(resolve);
-          animation.addEventListener('cancel', resolver, listenerOptions);
-          animation.addEventListener('finish', resolver, listenerOptions);
-
-          animation.cancel();
-        });
-      })
-    );
-  }
-
-  public async playExclusive(animation: AnimationReferenceMetadata) {
-    const [_, event] = await Promise.all([
-      this.stopAll(),
-      this.play(animation),
-    ]);
+  /** Cancels all active animations on the target element. */
+  public cancelAll(): Promise<void> {
+    for (const animation of this._target.getAnimations()) {
+      animation.cancel();
+    }
 
-    return event.type === 'finish';
+    return Promise.resolve();
   }
-
-  public hostConnected() {}
 }
 
 /**
@@ -91,14 +118,14 @@ class AnimationController implements ReactiveController {
 export function addAnimationController(
   host: ReactiveControllerHost & HTMLElement,
   target?: Ref<HTMLElement> | HTMLElement
-) {
+): AnimationController {
   return new AnimationController(host, target);
 }
 
-type ViewTransitionResult = {
-  transition?: ViewTransition;
-};
-
+/**
+ * Initiates a View Transition if supported by the browser and not suppressed by
+ * the 'prefers-reduced-motion' setting.
+ */
 export function startViewTransition(
   callback?: ViewTransitionUpdateCallback
 ): ViewTransitionResult {