Changelog: Scroll to Top Button - v2.4.0 vs v3.1.0 (Developer Notes)
This details the technical modifications and refactoring between the two versions.
I. Architectural & Core Changes:
CSS Injection vs. Inline Styling:
- v2.4.0: Applied most base styles and all dynamic
:hover/:active styles directly via element.style using JavaScript (createButtonElement, setButtonHoverStyle, resetButtonStyles, setButtonPressStyle). Visibility/Opacity were also directly manipulated in JS (handleScrollEvent) with a setTimeout for the hide transition.
- v3.1.0: Major Change. Introduces CSS injection via
_injS. A <style> tag (#_sid) is added to the <head>. All base styles, :hover, :active pseudo-classes, and visibility transitions (opacity, visibility, transform) are now handled purely via CSS rules targeting the button's ID (#_bid) and a .visible class.
- Rationale: Reduces JS DOM style manipulation, leverages browser's CSS engine for better performance and rendering, cleaner separation of concerns, simplifies JS logic (removes hover/active handlers and visibility timeout).
Visibility/State Handling:
- v2.4.0: Used
shouldShowButton logic (checking showThreshold and bottomThreshold) and directly set element.style.opacity and element.style.visibility.
- v3.1.0: Simplified visibility logic (
_hSE). Only checks scroll position against _cfg.bh.shThrPx. Toggles a .visible class on the button element. The CSS handles the actual fade/show animation via transitions linked to this class. Removed the bottomThreshold logic.
Configuration Structure (APP_CONFIG vs _cfg):
- v2.4.0: Used
APP_CONFIG with more verbose nested object names (button, behavior, scroll).
- v3.1.0: Renamed to
_cfg with abbreviated nested names (b, bh, sc) and key names (e.g., size -> sz, transitionSpeed -> trMs). Breaking change for users with custom configurations.
Smooth Scroll Implementation (smoothScrollToTop vs _scT/_smS):
- v2.4.0: Single
smoothScrollToTop function. Included logic to adjust scrollDuration based on scroll.breakpoints. Used requestAnimationFrame and selected easing function.
- v3.1.0: Split into
_scT (controller) and _smS (animation loop).
-
_scT: Checks _cfg.bh.smScr. If true, checks _cfg.bh.natSmScr and browser support ('scrollBehavior' in document.documentElement.style) to potentially use native window.scrollTo({ behavior: 'smooth' }). Otherwise, calls _smS. If smScr is false, uses window.scrollTo({ behavior: 'auto' }).
-
_smS: Simplified custom animation loop. Uses performance.now() for timing. Removed the dynamic duration adjustment based on breakpoints. Uses cancelAnimationFrame if a new scroll is initiated before the previous finishes. Easing function selected via _gEF().
II. Added Features & Options:
- Native Smooth Scroll Option (
_cfg.bh.natSmScr): New boolean config to prefer browser's native implementation when available and enabled.
- Expanded Easing Functions (
_eas): Significantly increased the number of available easing functions compared to v2.4.0.
- SVG Path Configuration (
_cfg.b.svg.pd): Allows direct customization of the SVG icon path data via config.
- Accessibility Attributes (
_cfg.b.lbl): Added aria-label and title to the button, configured via _cfg.b.lbl.
-
@noframes Directive: Added to the UserScript header to prevent execution in iframes.
- Basic Initialization Error Handling: Wrapped
_init body in try...catch block.
III. Removed Functionality:
- Bottom Threshold (
behavior.bottomThreshold): The logic to hide the button when near the page bottom was removed.
- FPS Configuration (
scroll.fps): Removed as requestAnimationFrame handles frame timing natively.
- Dynamic Scroll Duration (
scroll.breakpoints): Removed complexity; scroll duration is now fixed per scroll action based on _cfg.sc.durMs.
- JS-based Hover/Active Styling: Replaced entirely by CSS pseudo-classes.
IV. Internal & Minor Changes:
- Element IDs: Button ID changed from
enhanced-scroll-button to estb-dxrk1e-s. Style ID estb-styles-dxrk1e-s added.
- Internal Naming Convention: Increased use of underscore prefix (
_) for internal functions/variables (e.g., _btn, _sto, _gSP).
- Debounce Function (
_deb): Simplified implementation compared to v2.4.0's debounce (removed immediate flag logic). Module-scoped timeout variable (_sto).
- Scroll Position Getter (
_gSP): Uses window.scrollY first, a more modern equivalent to pageYOffset.
- MutationObserver Target: Changed from
document.documentElement to document.body. Added attributes: false for potentially better performance.
- Default Values: Minor adjustments to default styling and behavior timings/thresholds (see code diff for specifics).
Summary:
Version 3.1.0 represents a significant refactoring towards using CSS for styling and transitions, simplifying JavaScript logic, and improving performance and maintainability. It introduces native smooth scroll support and more easing options while removing some less essential complexity (like bottom threshold and dynamic scroll speed). The configuration structure change is the main breaking change for end-users modifying the script.
