=== BWW Letter Animator ===
Contributors: benworldwide
Tags: elementor, animation, heading, text effect, scroll animation
Requires at least: 5.5
Tested up to: 6.6
Requires PHP: 7.2
Stable tag: 1.0.0
License: GPLv2 or later

Scroll-triggered, letter-by-letter title animations for any heading — as an
Elementor widget, or a shortcode for any other builder or theme.

== What it does ==

Adds a "Letter animator" widget (find it under the "BenWorldwide" category in
Elementor) that lets you type a title and pick:

* Animation style — "Stand up from flat" (letters start knocked over flat on
  their side and stand upright) or "Fall & bounce" (letters drop from above
  and bounce into place).
* Which letters animate — all letters, first letter only, last letter only,
  first 3, last 3, or custom letter positions (e.g. "1, 4, 7").
* Delay between letters, animation duration, and how much of the section
  must be visible before it plays.
* Whether it should only play the first time, or every time the section
  scrolls back into view.

The animation NEVER plays on page load. It only plays once the visitor
scrolls the section into view (using IntersectionObserver), which is the
standard, professional way to do this — the same technique used by
GSAP ScrollTrigger / AOS-style scroll reveal effects.

It also respects visitors' "reduce motion" accessibility setting, and always
keeps the real text readable to screen readers.

== Using it in Elementor ==

1. Install and activate the plugin.
2. Edit any page with Elementor, drag in the "Letter animator" widget
   (under the BenWorldwide category — search "letter" if you don't see it).
3. Type your title, pick an animation style and which letters should animate,
   then style it (font, size, color, alignment) like any other Elementor
   heading, in the Style tab.
4. Preview and scroll the section out of view and back in — the animation
   only plays on scroll, never immediately.

== Using it anywhere else (shortcode) ==

If a section isn't built with Elementor (a classic widget area, a theme
template, another page builder's HTML/shortcode block, etc.) use the
shortcode instead:

	[bww_letter_animate text="Trusted by" tag="h2" effect="standup" scope="all"]

All options as shortcode attributes:

* text        — the title text.
* tag         — h1, h2, h3, h4, h5, h6, div, span, or p (default h2).
* effect      — standup or dropbounce (default standup).
* scope       — all, first, last, first3, last3, or custom (default all).
* custom      — only used when scope="custom", e.g. custom="1,4,7".
* stagger     — milliseconds between each animated letter (default 60).
* duration    — animation length in milliseconds (default 600).
* threshold   — 0 to 1, how much of the element must be visible to trigger
                (default 0.4).
* once        — yes or no. "no" replays every time it re-enters view
                (default yes).
* fallen_color — CSS color for a letter while it's flat/falling, before it
                lands (default #9a9a9a). It fades to the normal text color
                as each letter stands up. Leave blank to skip the color
                change entirely.
* baseline_offset — only relevant to effect="standup". A small nudge in em
                (e.g. 0.05 or -0.05) in case a particular font/theme needs
                the fallen letter moved a touch to sit exactly on the line.
                Default 0.
* class       — extra CSS class if you want to hook custom styling.

== About the "stand up from flat" effect ==

Each letter pivots from its own base — the same line the standing letters
rest on — so a fallen letter lies flat along that line rather than hanging
below it. Letters also always tip INWARD across the word (the first half
tips right, the second half tips left), so a fallen letter overlaps a
neighboring letter instead of swinging out past the start or end of the
title and making it look wider. This is deliberate and is what makes
"last letter only" or "first letter only" look right by default.

Example — only the last letter falls and bounces, replaying every time:

	[bww_letter_animate text="TRUSTED BY" tag="h3" effect="dropbounce" scope="last" once="no"]

== Notes ==

* Works with or without Elementor. If Elementor isn't active, only the
  shortcode is available (the plugin doesn't require Elementor).
* Safe to use on multiple headings on the same page — each one is
  independent and triggers on its own scroll position.
