=== SW34 Easy Scroll ===
Contributors: studioweb34
Tags: smooth scroll, scrolling, lenis, scroll animation
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Smooth scrolling powered by Lenis, with full control over the scroll settings and a global on/off switch.

== Description ==

This plugin brings the Lenis smooth-scrolling library to the front end of your
site and exposes its settings on a single screen: animation model, duration,
easing curve, mouse wheel, keyboard, orientation, anchor links, and who and
where smooth scrolling should apply to.

Every setting is about scrolling. There is no analytics, no upsell, no banner.

= Keyboard scrolling =

Lenis registers no keyboard listener, so out of the box the wheel glides and the
arrow keys jump — two contradictory behaviours on the same page. This plugin
fills that gap: arrow keys, Page Up and Page Down, Space, Home and End all
glide, with a configurable distance per arrow press.

It gets out of the way where it should: form fields, buttons, media players,
menus, sliders and scrollable areas keep their own key handling, and the
keyboard is left alone entirely for visitors who asked for reduced motion.

= What you should know =

* The Lenis library is **bundled with the plugin**, both minified and as
  readable source (`assets/js/lenis.js`, served when `SCRIPT_DEBUG` is on).
  No CDN is contacted and no data leaves your server. Lenis is released under
  the MIT licence — see `assets/js/LICENSE-lenis.txt`.
* Smooth scrolling is switched off automatically in the admin area, in the
  Customizer and inside page builders (Divi, Elementor, Beaver Builder, Oxygen,
  Bricks, WPBakery, Brizy, Thrive).
* If your theme or another plugin already registered Lenis under the `lenis`
  script handle, this plugin reuses that copy rather than loading a second one.
* "Respect reduced motion" is on by default: visitors who asked their operating
  system for less animation get native scrolling back.
* The master switch is a real switch. When it is off, the plugin loads no CSS
  and no JavaScript at all on the public site.

= Privacy =

The plugin contacts no external server, including Studio Web 34's own. It sets
no cookie, collects no personal data and contains no tracking of any kind.

= For developers =

Filters and actions:

* `sw34_easy_scroll_post_types` — the post types offered the per-page switch.
* `sw34_easy_scroll_should_run` (bool) — final say on whether smooth scrolling runs.
* `sw34_easy_scroll_options` (array) — the settings as read from the database.
* `sw34_easy_scroll_config` (array, array) — the JavaScript configuration before it
  is serialised. This is where you re-enable Lenis options the settings screen
  deliberately does not expose, such as `infinite`.
* `sw34_easy_scroll_settings_saved` (array) — fires after the settings are saved.
* `sw34_easy_scroll_settings_reset` (array) — fires after the settings are reset.

JavaScript API:

* `window.SW34EasyScroll.instance` — the Lenis instance.
* `window.SW34EasyScroll.start()` / `window.SW34EasyScroll.destroy()`.
* `sw34-easy-scroll:ready` and `sw34-easy-scroll:destroyed` events on `document`.
* `window.lenis` as well, if the matching setting is enabled — for scripts such
  as GSAP ScrollTrigger that expect that global.

== Installation ==

1. Upload the `sw34-easy-scroll` folder to `/wp-content/plugins/`.
2. Activate the plugin.
3. Open the **Smooth Scroll** menu in the admin sidebar.

If your theme has a sticky header, enter its height under "Top offset" in the
anchor links section, otherwise anchor targets end up underneath it.

== Frequently Asked Questions ==

= Scrolling feels wrong inside a map, a code editor or a modal. =

Add a CSS selector for that element under "Excluded areas". The
`data-lenis-prevent` attribute is also recognised without any setting.

= Can I use it with GSAP ScrollTrigger? =

Yes. Enable "Expose the instance as window.lenis", then drive ScrollTrigger
from the `sw34-easy-scroll:ready` event.

= Does it work on mobile? =

The plugin never smooths touch scrolling: native mobile scrolling is more
responsive and better received, so there is no setting for it. Everything else
still applies, and "Disable on touch devices" turns the plugin off entirely on
phones and tablets if that is what you want.

= How do I turn it off on one page? =

Open that page in the editor and tick "Disable smooth scrolling on this page"
in the **Smooth scrolling** box in the sidebar. For a whole section of the site,
use a wildcard path such as `/my-account/*` under "Excluded pages" instead.

= Can I keep native scrolling for myself while I build the site? =

Yes. Set "Who gets smooth scrolling" to "Everyone except administrators".

= Anchor links jump instead of gliding. =

Check that "Animate anchor links" is on. When it is, this plugin takes anchor
clicks in the capture phase and stops them there, so a theme running its own
anchor scrolling — Divi does — cannot overwrite the animation. If you would
rather keep your theme's behaviour, turn this setting off.

= Can a scrollable area inside the page be animated too? =

No. Lenis animates the document, not the boxes inside it. "Let nested areas
scroll" only hands the wheel back to that box so the page does not move
instead; the box then scrolls natively, without inertia. Animating it would
take a second Lenis instance bound to that element.

= The arrow keys scroll the page while I am filling in a form. =

They should not — form fields are excluded. If it happens on a custom field,
add a selector for it under "Excluded areas", and please report it.

== Other Notes ==

= Internationalization =

Source language is English. French (`fr_FR`) and Spanish (`es_ES`) catalogues
are bundled — 108 strings, 104 translated in each; the four left untranslated
are the plugin name, the author name and the two URLs, which stay the same in
every language.

Everything visible is translatable, including the strings used by the settings
screen's JavaScript, which are passed through `wp_localize_script()` rather than
written into the `.js` file where gettext would never see them.

= Credits =

Smooth scrolling is powered by [Lenis](https://lenis.dev/) 1.3.26 by
darkroom.engineering, released under the MIT licence. Source repository:
https://github.com/darkroomengineering/lenis — the bundled files are
`assets/js/lenis.min.js`, its readable source `assets/js/lenis.js`, and the
stylesheet `assets/css/lenis.css`. The licence text is in
`assets/js/LICENSE-lenis.txt`.

== Screenshots ==

1. The settings screen: master switch at the top, then animation, mouse wheel,
   keyboard, orientation, anchor links, behaviour, integration, scope and reset.
2. The "Smooth scrolling" box in the editor sidebar, to turn smooth scrolling
   off on a single page.

== Changelog ==
= 1.0.0 =
First release.
