@bquery/bquery 1.2.0 → 1.3.0

package/src/motion/animate.ts

@@ -0,0 +1,113 @@
+/**
+ * Web Animations helpers.
+ *
+ * @module bquery/motion
+ */
+
+import { prefersReducedMotion } from './reduced-motion';
+import type { AnimateOptions } from './types';
+
+/** @internal */
+const isStyleValue = (value: unknown): value is string | number =>
+  typeof value === 'string' || typeof value === 'number';
+
+/**
+ * Convert camelCase property names to kebab-case for CSS.
+ * @internal
+ */
+const toKebabCase = (str: string): string => {
+  return str.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+};
+
+/** @internal */
+export const applyFinalKeyframeStyles = (
+  element: Element,
+  keyframes: Keyframe[] | PropertyIndexedKeyframes
+): void => {
+  const htmlElement = element as HTMLElement;
+  const style = htmlElement.style;
+
+  if (Array.isArray(keyframes)) {
+    const last = keyframes[keyframes.length - 1];
+    if (!last) return;
+    for (const [prop, value] of Object.entries(last)) {
+      if (prop === 'offset' || prop === 'easing' || prop === 'composite') continue;
+      if (isStyleValue(value)) {
+        // Convert camelCase to kebab-case for CSS properties
+        const cssProp = prop.startsWith('--') ? prop : toKebabCase(prop);
+        style.setProperty(cssProp, String(value));
+      }
+    }
+    return;
+  }
+
+  for (const [prop, value] of Object.entries(keyframes)) {
+    if (prop === 'offset' || prop === 'easing' || prop === 'composite') continue;
+    const finalValue = Array.isArray(value) ? value[value.length - 1] : value;
+    if (isStyleValue(finalValue)) {
+      // Convert camelCase to kebab-case for CSS properties
+      const cssProp = prop.startsWith('--') ? prop : toKebabCase(prop);
+      style.setProperty(cssProp, String(finalValue));
+    }
+  }
+};
+
+/**
+ * Animate an element using the Web Animations API with reduced-motion fallback.
+ *
+ * @param element - Element to animate
+ * @param config - Animation configuration
+ * @returns Promise that resolves when animation completes
+ *
+ * @example
+ * ```ts
+ * await animate(element, {
+ *   keyframes: [{ opacity: 0 }, { opacity: 1 }],
+ *   options: { duration: 200, easing: 'ease-out' },
+ * });
+ * ```
+ */
+export const animate = (element: Element, config: AnimateOptions): Promise<void> => {
+  const { keyframes, options, commitStyles = true, respectReducedMotion = true, onFinish } = config;
+
+  if (respectReducedMotion && prefersReducedMotion()) {
+    if (commitStyles) {
+      applyFinalKeyframeStyles(element, keyframes);
+    }
+    onFinish?.();
+    return Promise.resolve();
+  }
+
+  const htmlElement = element as HTMLElement;
+  if (typeof htmlElement.animate !== 'function') {
+    if (commitStyles) {
+      applyFinalKeyframeStyles(element, keyframes);
+    }
+    onFinish?.();
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve) => {
+    const animation = htmlElement.animate(keyframes, options);
+    let finalized = false;
+    const finalize = () => {
+      if (finalized) return;
+      finalized = true;
+      if (commitStyles) {
+        if (typeof animation.commitStyles === 'function') {
+          animation.commitStyles();
+        } else {
+          applyFinalKeyframeStyles(element, keyframes);
+        }
+      }
+      animation.cancel();
+      onFinish?.();
+      resolve();
+    };
+
+    animation.onfinish = finalize;
+    if (animation.finished) {
+      animation.finished.then(finalize).catch(finalize);
+    }
+  });
+};

package/src/motion/easing.ts

@@ -0,0 +1,40 @@
+/**
+ * Easing helpers.
+ *
+ * @module bquery/motion
+ */
+
+import type { EasingFunction } from './types';
+
+const clamp = (value: number) => Math.min(1, Math.max(0, value));
+
+export const linear: EasingFunction = (t) => clamp(t);
+export const easeInQuad: EasingFunction = (t) => clamp(t * t);
+export const easeOutQuad: EasingFunction = (t) => clamp(1 - (1 - t) * (1 - t));
+export const easeInOutQuad: EasingFunction = (t) =>
+  clamp(t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2);
+export const easeInCubic: EasingFunction = (t) => clamp(t * t * t);
+export const easeOutCubic: EasingFunction = (t) => clamp(1 - Math.pow(1 - t, 3));
+export const easeInOutCubic: EasingFunction = (t) =>
+  clamp(t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+export const easeOutBack: EasingFunction = (t) => {
+  const c1 = 1.70158;
+  const c3 = c1 + 1;
+  return clamp(1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2));
+};
+export const easeOutExpo: EasingFunction = (t) => clamp(t === 1 ? 1 : 1 - Math.pow(2, -10 * t));
+
+/**
+ * Named easing presets.
+ */
+export const easingPresets = {
+  linear,
+  easeInQuad,
+  easeOutQuad,
+  easeInOutQuad,
+  easeInCubic,
+  easeOutCubic,
+  easeInOutCubic,
+  easeOutBack,
+  easeOutExpo,
+};

package/src/motion/flip.ts

@@ -0,0 +1,176 @@
+/**
+ * FLIP animation helpers.
+ *
+ * @module bquery/motion
+ */
+
+import type { ElementBounds, FlipGroupOptions, FlipOptions } from './types';
+
+/**
+ * Capture the current bounds of an element for FLIP animation.
+ *
+ * @param element - The DOM element to measure
+ * @returns The element's current position and size
+ */
+export const capturePosition = (element: Element): ElementBounds => {
+  const rect = element.getBoundingClientRect();
+  return {
+    top: rect.top,
+    left: rect.left,
+    width: rect.width,
+    height: rect.height,
+  };
+};
+
+/**
+ * Perform a FLIP (First, Last, Invert, Play) animation.
+ * Animates an element from its captured position to its current position.
+ *
+ * @param element - The element to animate
+ * @param firstBounds - The previously captured bounds
+ * @param options - Animation configuration
+ * @returns Promise that resolves when animation completes
+ *
+ * @example
+ * ```ts
+ * const first = capturePosition(element);
+ * // ... DOM changes that move the element ...
+ * await flip(element, first, { duration: 300 });
+ * ```
+ */
+export const flip = (
+  element: Element,
+  firstBounds: ElementBounds,
+  options: FlipOptions = {}
+): Promise<void> => {
+  const { duration = 300, easing = 'ease-out', onComplete } = options;
+
+  // Last: Get current position
+  const lastBounds = capturePosition(element);
+
+  // Skip animation if element has zero dimensions (avoid division by zero)
+  if (lastBounds.width === 0 || lastBounds.height === 0) {
+    onComplete?.();
+    return Promise.resolve();
+  }
+
+  // Invert: Calculate the delta
+  const deltaX = firstBounds.left - lastBounds.left;
+  const deltaY = firstBounds.top - lastBounds.top;
+  const deltaW = firstBounds.width / lastBounds.width;
+  const deltaH = firstBounds.height / lastBounds.height;
+
+  // Skip animation if no change
+  if (deltaX === 0 && deltaY === 0 && deltaW === 1 && deltaH === 1) {
+    onComplete?.();
+    return Promise.resolve();
+  }
+
+  const htmlElement = element as HTMLElement;
+
+  // Feature check: fallback if Web Animations API is unavailable
+  if (typeof htmlElement.animate !== 'function') {
+    onComplete?.();
+    return Promise.resolve();
+  }
+
+  // Apply inverted transform
+  htmlElement.style.transform = `translate(${deltaX}px, ${deltaY}px) scale(${deltaW}, ${deltaH})`;
+  htmlElement.style.transformOrigin = 'top left';
+
+  // Force reflow
+  void htmlElement.offsetHeight;
+
+  // Play: Animate back to current position
+  return new Promise((resolve) => {
+    const animation = htmlElement.animate(
+      [
+        {
+          transform: `translate(${deltaX}px, ${deltaY}px) scale(${deltaW}, ${deltaH})`,
+        },
+        { transform: 'translate(0, 0) scale(1, 1)' },
+      ],
+      { duration, easing, fill: 'forwards' }
+    );
+
+    let finalized = false;
+    const finalize = () => {
+      if (finalized) return;
+      finalized = true;
+      htmlElement.style.transform = '';
+      htmlElement.style.transformOrigin = '';
+      onComplete?.();
+      resolve();
+    };
+
+    animation.onfinish = finalize;
+    // Handle cancel/rejection via the finished promise
+    if (animation.finished) {
+      animation.finished.then(finalize).catch(finalize);
+    }
+  });
+};
+
+/**
+ * FLIP helper for animating a list of elements.
+ * Useful for reordering lists with smooth animations.
+ *
+ * @param elements - Array of elements to animate
+ * @param performUpdate - Function that performs the DOM update
+ * @param options - Animation configuration
+ *
+ * @example
+ * ```ts
+ * await flipList(listItems, () => {
+ *   container.appendChild(container.firstChild); // Move first to last
+ * });
+ * ```
+ */
+export const flipList = async (
+  elements: Element[],
+  performUpdate: () => void,
+  options: FlipOptions = {}
+): Promise<void> => {
+  await flipElements(elements, performUpdate, options);
+};
+
+/**
+ * FLIP helper with optional stagger support.
+ *
+ * @param elements - Array of elements to animate
+ * @param performUpdate - Function that performs the DOM update
+ * @param options - Animation configuration
+ */
+export const flipElements = async (
+  elements: Element[],
+  performUpdate: () => void,
+  options: FlipGroupOptions = {}
+): Promise<void> => {
+  const { stagger, ...flipOptions } = options;
+
+  // First: Capture all positions
+  const positions = new Map<Element, ElementBounds>();
+  for (const el of elements) {
+    positions.set(el, capturePosition(el));
+  }
+
+  // Perform DOM update
+  performUpdate();
+
+  const total = elements.length;
+
+  // Animate each element
+  const animations = elements.map((el, index) => {
+    const first = positions.get(el);
+    if (!first) return Promise.resolve();
+    const delay = stagger ? stagger(index, total) : 0;
+    if (delay > 0) {
+      return new Promise((resolve) => setTimeout(resolve, delay)).then(() =>
+        flip(el, first, flipOptions)
+      );
+    }
+    return flip(el, first, flipOptions);
+  });
+
+  await Promise.all(animations);
+};