OverlayScrollbars/packages/overlayscrollbars/CHANGELOG.md

Changelog

2.0.0

OverlayScrollbars was rewritten from the ground up in TypeScript in a functional manner. The rewrite comes with multiple benefits:

• The library is much smaller now (about 50% smaller fully treeshaken)
• Modern browsers benefit greatly because compat code is inside plugins which are treeshaken if unused
• Multiple performance optimizations were made due to the new structure
• Framework Components benefit of the pure parameter for options and events (same input produces same output)
• TypeScript definitions are always up to date (@types/overlayscrollbars is obsolete now)

New Features:

• If applied to body all the native functionality in modern browsers (e.g. swipe down to refresh on mobile, scroll restoration etc.) is preserved (#376, #425, #273, #320)
• If you scroll while the cursor hovers a scrollbar element the viewport is now scrolled (#128, #322)
• The initialization process can be fully customized now. This makes it possible to itegrate with other plugins / libraries (#432, #304, #149, #148, #139, #49)
• Scrollbars can be cloned and positioned anywhere in the DOM tree. (#404, #323, #158, #17)
• The update behavior of the MutationObserver for the content can be customized with the update options. (#307, #183, #23)
• Works now without adjustments with CSS-Grid, CSS-Flexbox etc.
• Supports all kind of input devices additionally to mouse and touch. (Uses native pointer-events now)
• Exports a esm version which can be treeshaken

Breaking changes:

• Browser support changed. The minimal version is now IE11.

• The scroll function is missing. (WIP will be added as a plugin)

• Initialization to textarea element is not suppored. (WIP will be added as a plugin)

• extensions are replaced with plugins. Plugins are more powerful but work nothing like extensions.

• Any helper functions for extensions are removed.

• TypesScript definitions changed completely.

• CSS styles changed completely.

• There is no jQuery version anymore and no jQuery compat functionality

• The following changed for the initialization:

  • Arrays of elements are not supported anymore. If you want to initialize the plugin to multiple elements, you have to loop over them.
  • Since the initialization is now fully customizable, the plugin won't have special behavior anymore if it has children with os- classnames
  • The third parameter are events now instead of eventsions since extensions are removed

• The following options were removed / replaced / renamed:

  • resize is removed
  • sizeAutoCapable is removed (works always now)
  • clipAlways is removed (works automatically now)
  • normalizeRTL is removed since the scroll function isn't implemented yet there is nothing to normalize
  • autoUpdate is removed since all browser support the MutationObserver api there is no need for customizing a update loop
  • autoUpdateInterval is removed
  • className is replaced with scrollbars.theme
  • updateOnLoad is replaced with update.elementEvents
  • nativeScrollbarsOverlaid.initialize is replaced with the Initialization concept. You can pass a object as target now where you can specify when to cancel the initialization of the plugin.
  • nativeScrollbarsOverlaid.showNativeScrollbars: is renamed to showNativeOverlaidScrollbars
  • scrollbars.dragScrolling is renamed to scrollbars.dragScroll
  • scrollbars.clickScrolling is renamed to scrollbars.clickScroll and animates the scroll change only with the ClickScrollPlugin otherwise its instant
  • scrollbars.touchSupport is replaced with scrollbars.pointers
  • scrollbars.snapHandle is removed
  • textarea is removed since textarea initialization isn't possible yet
  • callbacks is removed / replaced with the events concept. You can pass listeners / callback separately to the options. The this context is now undefined as a replacement each event recieves the instance as its first argument.
    • onScrollStart is removed
    • onScrollStop is removed
    • onInitialized is replaced with the initialized event
    • onUpdated is replaced with the updated the
    • onDestroyed is replaced with the destroyed event
    • onScroll is replaced with the scroll event
    • onInitializationWithdrawn is replaced with the destroyed event (if the second argument canceled is true)
    • onOverflowChanged is replaced with the updated event (its second argument holds the information whether the overflow changed)
    • onOverflowAmountChanged is replaced with theupdated event (its second argument holds the information whether the overflow amount changed and how much)
    • onDirectionChanged is replaced with the updated event (its second argument holds the information whether the direction changed)
    • onContentSizeChanged is replaced with the updated event (its second argument holds the information whether the content got mutated)
    • onHostSizeChanged is replaced with the updated event (its second argument holds the information whether the host got mutated / its size changed)

• The following instance methods were removed / replaced / renamed:

  • sleep() is removed since it doesn't fit into the new structure and shouldn't be needed anymore
  • ext() is removed
  • addExt() is removed
  • removeExt() is removed
  • scroll() is removed (WIP)
  • scrollStop() is removed (WIP)
  • getElements() is renamed to elements() and doesn't support any argumens anymore.
  • getState() is renamed to state() and doesn't support any argumens anymore.

• The following static methods were removed / replaced / renamed:

  • extension() is removed
  • defaultOptions() is replaced with env().getDefaultOptions() and env().setDefaultOptions()
  • globals() is replaced with env()

• If you used any fields from the globals() result, please refer to the TypeScript definitions for the correct replacement in env()

Theming changes:

• Because scrollbars can be cloned and positioned anywhere in the DOM, themes which worked in v1 have to be adapted slightly:
  • .os-scrollbar elements now don't rely on its parent element. Selectors like .os-theme-dark > .os-scrollbar-vertical are now .os-theme-dark.os-scrollbar-vertical
  • the .os-host-rtl class is replaced with .os-scrollbar-rtl. Selectors like .os-theme-dark.os-host-rtl > .os-scrollbar-horizontal are now .os-theme-dark.os-scrollbar-rtl.os-scrollbar-horizontal