flet-box 0.0.0-stage → 1.0.2

package/src/animations/AnimatedText.js

@@ -0,0 +1,105 @@
+/**
+ * AnimatedText - Animates individual characters of a Text widget.
+ *
+ * Splits the original text into individual letter widgets, wraps each one in
+ * an {@link AnimatedBox}, and lays them out in a flex container. Supports both
+ * simultaneous and staggered (per-character delay) animation modes.
+ *
+ * @module animations/AnimatedText
+ */
+import { Container } from "../widgets/Container.js";
+import { AnimatedBox } from "./AnimatedBox.js";
+import { Text } from "../widgets/Text.js";
+
+/**
+ * Renders each character of a Text widget as an independently animated element.
+ *
+ * @param {object}          props
+ * @param {HTMLElement}     props.child            - A Text widget whose characters will be animated.
+ * @param {Array<object>}   [props.animations]     - Animation descriptors passed to each character's
+ *   AnimatedBox. When absent or empty the original `child` is returned unchanged.
+ * @param {boolean}         [props.sameTime=false] - When `true`, all characters animate simultaneously
+ *   (no per-character delay). When `false`, each character is delayed by `delayBetween` seconds
+ *   multiplied by its index.
+ * @param {number}          [props.delayBetween=0.1] - Seconds between consecutive character animations
+ *   (only used when `sameTime` is `false`).
+ * @param {"row"|"column"}  [props.orientation="row"] - Flex direction for the character container.
+ *   `"row"` lays characters horizontally (normal reading order);
+ *   `"column"` stacks them vertically.
+ * @returns {HTMLElement|null} A flex Container holding each animated letter, or `null` if no
+ *   `child` was provided.
+ */
+export const AnimatedText = ({
+  child,
+  animations,
+  sameTime = false,
+  delayBetween = 0.1,
+  orientation = "row",
+}) => {
+  if (!child) return null;
+  if (!animations || animations.length === 0) return child;
+
+  // Extract text content and props from the original Text widget
+  const originalText = child._props?.text || child.textContent || "";
+  const originalProps = { ...(child._props || {}) };
+  // Ensure no background animation styles bleed into individual letter widgets
+  delete originalProps.animations;
+
+  const container = Container({
+    display: "flex",
+    flexDirection: orientation === "row" ? "row" : "column",
+    flexWrap: orientation === "row" ? "wrap" : "nowrap",
+    alignItems: orientation === "row" ? "center" : "flex-start",
+  });
+
+  const letters = originalText.split("");
+
+  letters.forEach((letter, index) => {
+    // Render spaces as fixed-width spacers rather than animated characters
+    if (letter === " ") {
+      const space = Container({
+        textContent: " ",
+        display: "inline-block",
+        width: orientation === "row" ? "0.3em" : "100%",
+        height: orientation === "column" ? "0.3em" : "auto",
+      });
+      container.appendChild(space);
+      return;
+    }
+
+    // Compute per-character delay based on position (0 when sameTime is true)
+    const baseDelay = sameTime ? 0 : index * delayBetween;
+
+    // Copy all animation descriptors, overriding delay with the per-character value
+    const letterAnimations = animations.map((anim) => ({
+      ...anim,
+      delay: `${baseDelay}s`,
+    }));
+
+    // Createste a new Text widget for this single character, inheriting all original
+    // text props (font, color, size, etc.) but rendering only the one letter.
+    const letterWidget = Text({
+      ...originalProps,
+      text: letter,
+      children: undefined,
+    });
+
+    // Match the flex layout of the container
+    letterWidget.style.display =
+      orientation === "row" ? "inline-block" : "block";
+    if (orientation === "column") {
+      letterWidget.style.textAlign = "center";
+    }
+
+    const animatedLetter = AnimatedBox({
+      animations: letterAnimations,
+      child: letterWidget,
+    });
+
+    container.appendChild(animatedLetter);
+  });
+
+  return container;
+};
+
+export default AnimatedText;

package/src/animations/MatrixRain.js

@@ -0,0 +1,220 @@
+/**
+ * MatrixRain - Canvas-based Matrix-style falling character animation.
+ *
+ * Renders a stream of randomly chosen characters cascading downward in a
+ * Matrix-green color scheme. Works in both `"fixed"` (full-viewport) and
+ * `"absolute"` (parent-relative) positioning modes.
+ *
+ * The returned `<canvas>` element has a `_cleanup()` method attached to it.
+ * Call it when removing the canvas from the DOM to cancel the animation loop,
+ * detach event listeners, and disconnect any ResizeObserver.
+ *
+ * @module animations/MatrixRain
+ */
+
+/**
+ * Creates and starts a Matrix-rain animation on a `<canvas>` element.
+ *
+ * @param {object}  [props={}]
+ * @param {string}  [props.chars="01アイウエオ…"] - Character pool to draw from.
+ *   Defaults to a mix of digits and katakana.
+ * @param {number}  [props.fontSize=16]            - Column width and character height in pixels.
+ * @param {number}  [props.speed=0.5]              - Base drop speed (rows per frame).
+ *   Each drop also adds a random jitter up to `speed` per frame.
+ * @param {number}  [props.fadeAmount=0.05]        - Opacity of the black overlay drawn each frame,
+ *   controlling how quickly old characters fade. Higher = faster fade.
+ * @param {number}  [props.resetProbability=0.975] - Probability threshold above which a drop that
+ *   has passed the bottom resets to the top. Values closer to 1 make resets rarer.
+ * @param {boolean} [props.useDynamicColor=true]   - When `true`, character brightness increases
+ *   toward the bottom of the canvas. When `false`, a flat `#0f0` green is used.
+ * @param {"fixed"|"absolute"} [props.position="fixed"] - CSS `position` of the canvas.
+ *   Use `"absolute"` to confine the rain inside a positioned parent element.
+ * @param {number}  [props.zIndex=1]               - CSS `z-index` of the canvas. Use a low value
+ *   (e.g. `1` or even a negative number) to render behind other content.
+ * @returns {HTMLCanvasElement} The canvas element, already appended with an animation loop
+ *   running. Attach `canvas._cleanup()` to your unmount lifecycle to clean up.
+ */
+export const MatrixRain = (props = {}) => {
+  const {
+    chars = "01アイウエオカキクケコサシスセソタチツテトナニヌネノハヒフヘホマミムメモヤユヨラリルレロワヲン",
+    fontSize = 16,
+    speed = 0.5,
+    fadeAmount = 0.05,
+    resetProbability = 0.975,
+    useDynamicColor = true,
+    position = "fixed",
+    zIndex = 1, // Low default so the canvas renders behind other UI elements
+  } = props;
+
+  let canvas = null;
+  let ctx = null;
+  let animationId = null;
+  let drops = [];
+  let columns = 0;
+  let resizeObserver = null;
+
+  /**
+   * Determines the canvas dimensions based on positioning mode.
+   * In `"absolute"` mode, dimensions come from the parent element's bounding rect.
+   * In `"fixed"` mode (default), the full viewport size is used.
+   *
+   * @returns {{ width: number, height: number }}
+   */
+  const getCanvasSize = () => {
+    const parent = canvas?.parentElement;
+    if (position === "absolute" && parent) {
+      const rect = parent.getBoundingClientRect();
+      return {
+        width: Math.max(1, Math.round(rect.width)),
+        height: Math.max(1, Math.round(rect.height)),
+      };
+    }
+    return {
+      width: window.innerWidth,
+      height: window.innerHeight,
+    };
+  };
+
+  /**
+   * Resizes the canvas to match its container, recalculates column count,
+   * and resets all drop positions. Also attaches a ResizeObserver on first
+   * call when in `"absolute"` mode.
+   *
+   * @returns {void}
+   */
+  const resizeCanvas = () => {
+    if (!canvas) return;
+    if (
+      position === "absolute" &&
+      !resizeObserver &&
+      typeof ResizeObserver !== "undefined" &&
+      canvas.parentElement
+    ) {
+      resizeObserver = new ResizeObserver(resizeCanvas);
+      resizeObserver.observe(canvas.parentElement);
+    }
+    const { width, height } = getCanvasSize();
+    canvas.width = width;
+    canvas.height = height;
+    columns = Math.floor(canvas.width / fontSize);
+    drops = Array.from({ length: columns }, () => Math.random() * -100);
+  };
+
+  /**
+   * Returns a random character from the configured character pool.
+   *
+   * @returns {string} A single character.
+   */
+  const getRandomChar = () => chars[Math.floor(Math.random() * chars.length)];
+
+  /**
+   * Computes the fill color for a character at a given vertical position.
+   * When `useDynamicColor` is `true`, brightness increases toward the bottom,
+   * creating a depth illusion. Otherwise returns a flat `#0f0`.
+   *
+   * @param {number} y            - Current y-coordinate of the character (pixels).
+   * @param {number} canvasHeight - Total canvas height in pixels.
+   * @returns {string} A CSS color string.
+   */
+  const getColor = (y, canvasHeight) => {
+    if (!useDynamicColor) return "#0f0";
+    const intensity = 100 + (y / canvasHeight) * 155;
+    return `rgb(0, ${Math.min(255, intensity)}, 0)`;
+  };
+
+  /**
+   * Initializes the canvas element, sets its styles, and starts the draw loop.
+   *
+   * @returns {void}
+   */
+  const init = () => {
+    canvas = document.createElement("canvas");
+    resizeCanvas();
+    canvas.style.display = "block";
+    canvas.style.position = position;
+    canvas.style.top = "0";
+    canvas.style.left = "0";
+    canvas.style.zIndex = zIndex;
+    canvas.style.pointerEvents = "none";
+
+    ctx = canvas.getContext("2d");
+
+    draw();
+  };
+
+  /**
+   * Renders a single animation frame: applies a semi-transparent black overlay
+   * to fade previous characters, then draws each column's next character at its
+   * current drop position and advances the drop.
+   *
+   * Schedules itself via `requestAnimationFrame` until cleanup is called.
+   *
+   * @returns {void}
+   */
+  const draw = () => {
+    if (!ctx || !canvas) return;
+
+    // Semi-transparent black overlay produces the trailing-fade effect
+    ctx.fillStyle = `rgba(0, 0, 0, ${fadeAmount})`;
+    ctx.fillRect(0, 0, canvas.width, canvas.height);
+
+    ctx.font = `${fontSize}px monospace`;
+
+    for (let i = 0; i < drops.length; i++) {
+      const char = getRandomChar();
+      const x = i * fontSize;
+      const y = drops[i] * fontSize;
+
+      ctx.fillStyle = getColor(y, canvas.height);
+      ctx.fillText(char, x, y);
+
+      // Reset drop to the top once it has passed the bottom edge
+      if (y > canvas.height && Math.random() > resetProbability) {
+        drops[i] = 0;
+      }
+
+      drops[i] += speed + Math.random() * speed;
+    }
+
+    animationId = requestAnimationFrame(draw);
+  };
+
+  // Initialize canvas and start animation
+  init();
+
+  /** Window resize handler — recalculates dimensions on viewport changes. */
+  const handleResize = () => {
+    resizeCanvas();
+  };
+
+  window.addEventListener("resize", handleResize);
+  if (position === "absolute" && typeof ResizeObserver !== "undefined") {
+    resizeObserver = new ResizeObserver(resizeCanvas);
+    if (canvas.parentElement) resizeObserver.observe(canvas.parentElement);
+  }
+
+  /**
+   * Stops the animation loop, removes event listeners, disconnects the
+   * ResizeObserver, and removes the canvas from the DOM.
+   *
+   * @returns {void}
+   */
+  const cleanup = () => {
+    if (animationId) cancelAnimationFrame(animationId);
+    window.removeEventListener("resize", handleResize);
+    if (resizeObserver) resizeObserver.disconnect();
+    if (canvas && canvas.parentNode) canvas.parentNode.removeChild(canvas);
+  };
+
+  // Chain cleanup so any previously assigned _cleanup is also called
+  const originalCleanup = canvas._cleanup;
+  canvas._cleanup = () => {
+    cleanup();
+    if (originalCleanup) originalCleanup();
+  };
+
+  // Return the canvas directly — not a wrapper container
+  return canvas;
+};
+
+export default MatrixRain;

package/src/animations/ParallaxBox.js

@@ -0,0 +1,369 @@
+/**
+ * ParallaxBox - A container that applies a parallax offset to its child content.
+ *
+ * Supports three interaction modes:
+ * - `"scroll"`: offset follows the window scroll position.
+ * - `"mouse"`:  offset tracks the pointer relative to the widget center.
+ * - `"hover"`:  offset snaps to a position based on where the pointer enters,
+ *               then resets on mouse leave.
+ *
+ * The returned element exposes public methods (`updateSpeed`, `updateDirection`,
+ * `setPosition`, `reset`) and a `_cleanup()` function that removes all event
+ * listeners when the element is destroyed.
+ *
+ * @module animations/ParallaxBox
+ */
+import { WidgetFactory } from "../widget-factory/index.js";
+import { AnimatedBox } from "../animations/AnimatedBox.js";
+
+/**
+ * Creates a parallax-effect container.
+ *
+ * @param {object}          [props={}]
+ * @param {"scroll"|"mouse"|"hover"} [props.type="scroll"]
+ *   Interaction mode that drives the parallax offset.
+ * @param {number}          [props.speed=0.5]
+ *   Multiplier applied to scroll distance or pointer deviation. Higher values
+ *   produce more pronounced movement.
+ * @param {"vertical"|"horizontal"|"both"} [props.direction="vertical"]
+ *   Which axes the parallax offset is applied to.
+ * @param {number}          [props.maxOffset=100]
+ *   Maximum pixel offset allowed in each direction.
+ * @param {boolean}         [props.reverse=false]
+ *   When `true`, the movement direction is inverted.
+ * @param {HTMLElement|null} [props.child]
+ *   The content element to wrap. Returns `null` if not provided.
+ * @param {boolean}         [props.disabled=false]
+ *   When `true`, all parallax transforms are suppressed.
+ * @param {Function}        [props.onParallaxMove]
+ *   Callback invoked on every transform update with `{ x, y }` offsets.
+ * @param {number}          [props.duration=300]
+ *   CSS transition duration (ms) for smooth motion.
+ * @param {string}          [props.easing="ease-out"]
+ *   CSS transition timing function.
+ * @param {...*}            [props.rest]
+ *   Additional props forwarded to the outer container's WidgetFactory call.
+ * @returns {HTMLElement|null} The container element with the parallax wrapper
+ *   inside, or `null` if `child` was not provided.
+ */
+export const ParallaxBox = (props = {}) => {
+  let {
+    type = "scroll",
+    speed = 0.5,
+    direction = "vertical",
+    maxOffset = 100,
+    reverse = false,
+    child,
+    disabled = false,
+    onParallaxMove,
+    duration = 300,
+    easing = "ease-out",
+    ...rest
+  } = props;
+
+  if (!child) return null;
+
+  let containerRef = null;
+  let animationFrame = null;
+  let currentX = 0;
+  let currentY = 0;
+  let targetX = 0;
+  let targetY = 0;
+  let animatedContent = null;
+  let initialTimer = null;
+  const transitionTimers = new Set();
+
+  /**
+   * Schedules removal of the CSS transition after it has finished playing,
+   * so subsequent programmatic transforms are instant rather than animated.
+   *
+   * @returns {void}
+   */
+  const clearTransitionLater = () => {
+    const timer = setTimeout(() => {
+      transitionTimers.delete(timer);
+      if (animatedContent) animatedContent.style.transition = "";
+    }, duration);
+    transitionTimers.add(timer);
+  };
+
+  /**
+   * Applies a CSS `transform` to the inner animated wrapper, clamped to
+   * `maxOffset`, respecting the active `direction` and `reverse` settings.
+   *
+   * @param {number}  x         - Desired horizontal offset in pixels.
+   * @param {number}  y         - Desired vertical offset in pixels.
+   * @param {boolean} [animate=true] - When `true`, a CSS transition is set;
+   *   when `false`, the transition is removed for an instant snap.
+   * @returns {void}
+   */
+  const applyTransform = (x, y, animate = true) => {
+    if (disabled) return;
+
+    let moveX = x;
+    let moveY = y;
+
+    if (direction === "vertical") moveX = 0;
+    if (direction === "horizontal") moveY = 0;
+
+    if (reverse) {
+      moveX = -moveX;
+      moveY = -moveY;
+    }
+
+    moveX = Math.max(-maxOffset, Math.min(maxOffset, moveX));
+    moveY = Math.max(-maxOffset, Math.min(maxOffset, moveY));
+
+    targetX = moveX;
+    targetY = moveY;
+
+    if (onParallaxMove) onParallaxMove({ x: moveX, y: moveY });
+
+    if (animatedContent) {
+      const transformParts = [];
+      if (direction === "horizontal" || direction === "both") {
+        transformParts.push(`translateX(${moveX}px)`);
+      }
+      if (direction === "vertical" || direction === "both") {
+        transformParts.push(`translateY(${moveY}px)`);
+      }
+      animatedContent.style.transform = transformParts.join(" ");
+      if (animate) {
+        animatedContent.style.transition = `transform ${duration}ms ${easing}`;
+      } else {
+        animatedContent.style.transition = "none";
+      }
+      clearTransitionLater();
+    }
+  };
+
+  /**
+   * Resets the inner wrapper's transform back to the origin (0, 0).
+   *
+   * @param {boolean} [animate=true] - Whether to animate the reset.
+   * @returns {void}
+   */
+  const resetTransform = (animate = true) => {
+    targetX = 0;
+    targetY = 0;
+    if (animatedContent) {
+      animatedContent.style.transform = "translateX(0) translateY(0)";
+      if (animate) {
+        animatedContent.style.transition = `transform ${duration}ms ${easing}`;
+      } else {
+        animatedContent.style.transition = "none";
+      }
+      clearTransitionLater();
+    }
+    if (onParallaxMove) onParallaxMove({ x: 0, y: 0 });
+  };
+
+  /**
+   * Window scroll event handler for `type="scroll"` mode.
+   * Converts the current scroll position into a parallax offset and calls
+   * `applyTransform` inside a `requestAnimationFrame` callback.
+   *
+   * @returns {void}
+   */
+  const handleScroll = () => {
+    if (disabled || type !== "scroll") return;
+    if (animationFrame) cancelAnimationFrame(animationFrame);
+
+    animationFrame = requestAnimationFrame(() => {
+      const scrollY = window.scrollY;
+      const scrollX = window.scrollX;
+      let moveY = scrollY * speed;
+      let moveX = scrollX * speed;
+
+      applyTransform(moveX, moveY, true);
+    });
+  };
+
+  /**
+   * Pointer move handler for `type="mouse"` and `type="hover"` modes.
+   * Calculates the pointer's normalized offset from the container center and
+   * converts it to a pixel offset scaled by `maxOffset`.
+   *
+   * @param {MouseEvent} e
+   * @returns {void}
+   */
+  const handleMouseMove = (e) => {
+    if (disabled || (type !== "mouse" && type !== "hover")) return;
+    if (animationFrame) cancelAnimationFrame(animationFrame);
+
+    animationFrame = requestAnimationFrame(() => {
+      const rect = containerRef.getBoundingClientRect();
+      const centerX = rect.left + rect.width / 2;
+      const centerY = rect.top + rect.height / 2;
+
+      let moveX = (e.clientX - centerX) / (rect.width / 2);
+      let moveY = (e.clientY - centerY) / (rect.height / 2);
+
+      moveX = moveX * maxOffset;
+      moveY = moveY * maxOffset;
+
+      applyTransform(moveX, moveY, true);
+    });
+  };
+
+  /**
+   * `mouseenter` handler for `type="hover"` mode.
+   * Snaps the offset to match the pointer's entry position within the element.
+   *
+   * @param {MouseEvent} e
+   * @returns {void}
+   */
+  const handleMouseEnter = (e) => {
+    if (disabled || type !== "hover") return;
+    const rect = containerRef.getBoundingClientRect();
+    const percentX = (e.clientX - rect.left) / rect.width;
+    const percentY = (e.clientY - rect.top) / rect.height;
+
+    let moveX = (percentX - 0.5) * maxOffset * 2;
+    let moveY = (percentY - 0.5) * maxOffset * 2;
+
+    applyTransform(moveX, moveY, true);
+  };
+
+  /**
+   * `mouseleave` handler — resets the parallax offset back to zero.
+   *
+   * @returns {void}
+   */
+  const handleMouseLeave = () => {
+    if (disabled || (type !== "mouse" && type !== "hover")) return;
+    resetTransform(true);
+  };
+
+  // Outer container — position: relative + overflow: hidden to clip the child
+  const container = WidgetFactory({
+    tag: "div",
+    position: "relative",
+    overflow: "hidden",
+    ...rest,
+  });
+
+  containerRef = container;
+
+  // Inner wrapper that receives CSS transforms; will-change enables GPU compositing
+  const animatedWrapper = WidgetFactory({
+    tag: "div",
+    willChange: "transform",
+    transition: `transform ${duration}ms ${easing}`,
+    transform: "translateX(0) translateY(0)",
+  });
+
+  // Append child content to the animated wrapper
+  if (child) {
+    if (child instanceof HTMLElement) {
+      animatedWrapper.appendChild(child);
+    } else if (typeof child === "string") {
+      const textNode = document.createTextNode(child);
+      animatedWrapper.appendChild(textNode);
+    } else if (Array.isArray(child)) {
+      child.forEach((item) => {
+        if (item instanceof HTMLElement) animatedWrapper.appendChild(item);
+        else if (typeof item === "string") {
+          animatedWrapper.appendChild(document.createTextNode(item));
+        }
+      });
+    }
+  }
+
+  animatedContent = animatedWrapper;
+  container.appendChild(animatedWrapper);
+
+  // Attach the appropriate event listeners for the selected interaction mode
+  if (type === "scroll") {
+    window.addEventListener("scroll", handleScroll);
+    // Run once after a short delay to sync with the current scroll position
+    initialTimer = setTimeout(() => {
+      initialTimer = null;
+      handleScroll();
+    }, 100);
+  } else if (type === "mouse" || type === "hover") {
+    container.addEventListener("mousemove", handleMouseMove);
+    container.addEventListener("mouseleave", handleMouseLeave);
+    if (type === "hover") {
+      container.addEventListener("mouseenter", handleMouseEnter);
+    }
+  }
+
+  // ========== PUBLIC METHODS ==========
+
+  /**
+   * Updates the parallax speed multiplier at runtime and re-applies the
+   * current transform (scroll mode only).
+   *
+   * @param {number} newSpeed - New speed multiplier.
+   * @returns {void}
+   */
+  container.updateSpeed = (newSpeed) => {
+    speed = newSpeed;
+    if (type === "scroll") handleScroll();
+  };
+
+  /**
+   * Updates the active parallax direction and re-applies or resets the transform.
+   *
+   * @param {"vertical"|"horizontal"|"both"} newDirection
+   * @returns {void}
+   */
+  container.updateDirection = (newDirection) => {
+    direction = newDirection;
+    if (type === "scroll") handleScroll();
+    else resetTransform(true);
+  };
+
+  /**
+   * Programmatically sets the parallax offset to a specific position.
+   *
+   * @param {number}  x              - Horizontal offset in pixels.
+   * @param {number}  y              - Vertical offset in pixels.
+   * @param {boolean} [animate=true] - Whether to animate the change.
+   * @returns {void}
+   */
+  container.setPosition = (x, y, animate = true) => {
+    applyTransform(x, y, animate);
+  };
+
+  /**
+   * Resets the parallax offset back to the origin (0, 0).
+   *
+   * @param {boolean} [animate=true] - Whether to animate the reset.
+   * @returns {void}
+   */
+  container.reset = (animate = true) => {
+    resetTransform(animate);
+  };
+
+  // ========== CLEANUP ==========
+
+  const originalCleanup = container._cleanup;
+  /**
+   * Removes all event listeners, cancels pending animation frames, clears
+   * timers, and calls any previously assigned `_cleanup` function.
+   *
+   * @returns {void}
+   */
+  container._cleanup = () => {
+    if (type === "scroll") {
+      window.removeEventListener("scroll", handleScroll);
+    } else {
+      container.removeEventListener("mousemove", handleMouseMove);
+      container.removeEventListener("mouseleave", handleMouseLeave);
+      if (type === "hover") {
+        container.removeEventListener("mouseenter", handleMouseEnter);
+      }
+    }
+    if (animationFrame) cancelAnimationFrame(animationFrame);
+    if (initialTimer) clearTimeout(initialTimer);
+    transitionTimers.forEach((timer) => clearTimeout(timer));
+    transitionTimers.clear();
+    if (originalCleanup) originalCleanup();
+  };
+
+  return container;
+};
+
+export default ParallaxBox;