v2.10.0

KingSora · KingSora · commit b7a96af53a8f · 2024-07-29T15:36:01.000+02:00
diff --git a/README.md b/README.md
@@ -376,9 +376,9 @@ Indicates whether you can drag the scrollbar handles for scrolling.
 
 | type  | default |
 | :--- | :--- |
-| `boolean` | `false` |
+| `boolean \| 'instant'` | `false` |
 
-> __Note__: This options requires the **ClickScrollPlugin** to work.
+> __Note__: If set to `true` the **ClickScrollPlugin** is required.
 
 Indicates whether you can click on the scrollbar track for scrolling.
 
@@ -442,13 +442,55 @@ type Options = {
     autoHideDelay: number;
     // Whether the scrollbar's auto hide behavior is suspended until a scroll happened.
     autoHideSuspend: boolean;
-    // Whether its possible to drag the handle of a scrollbar to scroll the viewport.
+    // Whether it is possible to drag the handle of a scrollbar to scroll the viewport.
     dragScroll: boolean;
-    // Whether its possible to click the track of a scrollbar to scroll the viewport.
-    clickScroll: boolean;
+    // Whether it is possible to click the track of a scrollbar to scroll the viewport.
+    clickScroll: ScrollbarsClickScrollBehavior;
     // An array of pointer types that shall be supported.
     pointers: string[] | null;
   };
+
+// The overflow behavior of an axis.
+type OverflowBehavior =
+  // No scrolling is possible and the content is clipped.
+  | 'hidden'
+  // No scrolling is possible and the content isn't clipped.
+  | 'visible'
+  // Scrolling is possible if there is an overflow.
+  | 'scroll'
+  /**
+   * If the other axis has no overflow the behavior is similar to `visible`.
+   * If the other axis has overflow the behavior is similar to `hidden`.
+   */
+  | 'visible-hidden'
+  /**
+   * If the other axis has no overflow the behavior is similar to `visible`.
+   * If the other axis has overflow the behavior is similar to `scroll`.
+   */
+  | 'visible-scroll';
+
+// The scrollbars visibility behavior.
+type ScrollbarsVisibilityBehavior =
+  // The scrollbars are always visible.
+  | 'visible'
+  // The scrollbars are always hidden.
+  | 'hidden'
+  // The scrollbars are only visibile if there is overflow.
+  | 'auto';
+
+// The scrollbars auto hide behavior
+type ScrollbarsAutoHideBehavior =
+  // The scrollbars are never hidden automatically.
+  | 'never'
+  // The scrollbars are hidden unless the user scrolls.
+  | 'scroll'
+  // The scrollbars are hidden unless the pointer moves in the host element or the user scrolls.
+  | 'move'
+  // The scrollbars are hidden if the pointer leaves the host element or unless the user scrolls.
+  | 'leave';
+
+// The scrollbar click scroll behavior.
+type ScrollbarsClickScrollBehavior = boolean | 'instant';
 };
 ```
 
@@ -588,7 +630,7 @@ const osInstance = OverlayScrollbars(document.body, {});
   | parameter | type | description |
   | :--- | :--- | :--- |
   | newOptions | `PartialOptions` | The new (partial) options which should be applied. |
-  | pure | `boolean / undefined` | Whether the options should be reset before the new options are added. |
+  | pure | `boolean \| undefined` | Whether the options should be reset before the new options are added. |
 
   | returns | description |
   | :--- | :--- |
@@ -601,7 +643,7 @@ const osInstance = OverlayScrollbars(document.body, {});
   | parameter | type | description |
   | :--- | :--- | :--- |
   | eventListeners | `EventListeners` | An object which contains the added listeners. The fields are the event names and the listeners. |
-  | pure | `boolean / undefined` | Whether all already added event listeners should be removed before the new listeners are added. |
+  | pure | `boolean \| undefined` | Whether all already added event listeners should be removed before the new listeners are added. |
 
   | returns | description |
   | :--- | :--- |
@@ -657,7 +699,7 @@ const osInstance = OverlayScrollbars(document.body, {});
 
   | parameter | type | description |
   | :--- | :--- | :--- |
-  | force | `boolean / undefined` |  Whether the update should force the cache to be invalidated. |
+  | force | `boolean \| undefined` |  Whether the update should force the cache to be invalidated. |
 
   | returns | description |
   | :--- | :--- |
@@ -689,7 +731,7 @@ const osInstance = OverlayScrollbars(document.body, {});
 
   | returns | description |
   | :--- | :--- |
-  | `object / undefined` | An object which describes the plugins instance modules instance or `undefined` if no instance was found. |
+  | `object \| undefined` | An object which describes the plugins instance modules instance or `undefined` if no instance was found. |
 
   #### TypeScript 
 
@@ -834,7 +876,7 @@ OverlayScrollbars.plugin(SomePlugin);
 
   | parameter | type | description |
   | :--- | :--- | :--- |
-  | newNonce | `string / undefined` | The nonce attribute for inline styles. |
+  | newNonce | `string \| undefined` | The nonce attribute for inline styles. |
 
   ### `plugin(plugin): object | undefined`
 
@@ -846,7 +888,7 @@ OverlayScrollbars.plugin(SomePlugin);
 
   | returns | description |
   | :--- | :--- |
-  | `object / void` | An object describing the plugin's static module instance or `void` if no instance was found. |
+  | `object \| void` | An object describing the plugin's static module instance or `void` if no instance was found. |
 
   ### `plugin(plugins): (object | void)[]`
 
@@ -858,7 +900,7 @@ OverlayScrollbars.plugin(SomePlugin);
 
   | returns | description |
   | :--- | :--- |
-  | `(object / void)[]` | An array describing the plugins static modules instances or `undefined` if no instance was found. |
+  | `(object \| void)[]` | An array describing the plugins static modules instances or `undefined` if no instance was found. |
 
   #### TypeScript
 
@@ -1050,10 +1092,10 @@ Custom themes can be done in several ways. The easiest and fastest way is to use
 | `.os-scrollbar-rtl` | Indicates a `RTL` direction of the host element the scrollbar belongs to. |
 | `.os-scrollbar-horizontal` | The root element of a horizontal scrollbar. |
 | `.os-scrollbar-vertical` | The root element of a vertical scrollbar. |
-| `.os-scrollbar-handle-interactive` | Indicates that the handle inside the scrollbar is interactive (`scrollbars.dragScroll` is `true`). |
-| `.os-scrollbar-track-interactive` | Indicates that the track inside the scrollbar is interactive (`scrollbars.clickScroll` is `true`). |
-| `.os-scrollbar-track` | The track element. This is the track of the nested handle element. If `scrollbars.clickScroll` is `true` this is the element users can click to change the scroll offset. |
-| `.os-scrollbar-handle` | The handle element. If `scrollbars.dragScroll` is `true` this is the handle users can drag to change the scroll offset. |
+| `.os-scrollbar-handle-interactive` | Indicates that the handle inside the scrollbar is interactive (`scrollbars.dragScroll` is not `false`). |
+| `.os-scrollbar-track-interactive` | Indicates that the track inside the scrollbar is interactive (`scrollbars.clickScroll` is not `false`). |
+| `.os-scrollbar-track` | The track element. This is the track of the nested handle element. If `scrollbars.clickScroll` is not `false` this is the element users can click to change the scroll offset. |
+| `.os-scrollbar-handle` | The handle element. If `scrollbars.dragScroll` is not `false` this is the handle users can drag to change the scroll offset. |
 
   If you create your own theme, please only use the classes listed above. All other classes are modifier classes used to change visibility, alignment and pointer-events of the scrollbars.
 
diff --git a/packages/overlayscrollbars/CHANGELOG.md b/packages/overlayscrollbars/CHANGELOG.md
@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.10.0
+
+### Features
+
+- The options `scrollbars.clickScroll` now supports the value `'instant'`. The `ClickScrollPlugin` is not required for it to work. [#645](https://github.com/KingSora/OverlayScrollbars/issues/645)
+
+### Improvements
+
+- Rewrite `clickScroll` animation for better performance and to support in and out easing for a smoother animation.
+
 ## 2.9.2
 
 ### Improvements
diff --git a/packages/overlayscrollbars/README.md b/packages/overlayscrollbars/README.md
@@ -376,9 +376,9 @@ Indicates whether you can drag the scrollbar handles for scrolling.
 
 | type  | default |
 | :--- | :--- |
-| `boolean` | `false` |
+| `boolean \| 'instant'` | `false` |
 
-> __Note__: This options requires the **ClickScrollPlugin** to work.
+> __Note__: If set to `true` the **ClickScrollPlugin** is required.
 
 Indicates whether you can click on the scrollbar track for scrolling.
 
@@ -442,13 +442,55 @@ type Options = {
     autoHideDelay: number;
     // Whether the scrollbar's auto hide behavior is suspended until a scroll happened.
     autoHideSuspend: boolean;
-    // Whether its possible to drag the handle of a scrollbar to scroll the viewport.
+    // Whether it is possible to drag the handle of a scrollbar to scroll the viewport.
     dragScroll: boolean;
-    // Whether its possible to click the track of a scrollbar to scroll the viewport.
-    clickScroll: boolean;
+    // Whether it is possible to click the track of a scrollbar to scroll the viewport.
+    clickScroll: ScrollbarsClickScrollBehavior;
     // An array of pointer types that shall be supported.
     pointers: string[] | null;
   };
+
+// The overflow behavior of an axis.
+type OverflowBehavior =
+  // No scrolling is possible and the content is clipped.
+  | 'hidden'
+  // No scrolling is possible and the content isn't clipped.
+  | 'visible'
+  // Scrolling is possible if there is an overflow.
+  | 'scroll'
+  /**
+   * If the other axis has no overflow the behavior is similar to `visible`.
+   * If the other axis has overflow the behavior is similar to `hidden`.
+   */
+  | 'visible-hidden'
+  /**
+   * If the other axis has no overflow the behavior is similar to `visible`.
+   * If the other axis has overflow the behavior is similar to `scroll`.
+   */
+  | 'visible-scroll';
+
+// The scrollbars visibility behavior.
+type ScrollbarsVisibilityBehavior =
+  // The scrollbars are always visible.
+  | 'visible'
+  // The scrollbars are always hidden.
+  | 'hidden'
+  // The scrollbars are only visibile if there is overflow.
+  | 'auto';
+
+// The scrollbars auto hide behavior
+type ScrollbarsAutoHideBehavior =
+  // The scrollbars are never hidden automatically.
+  | 'never'
+  // The scrollbars are hidden unless the user scrolls.
+  | 'scroll'
+  // The scrollbars are hidden unless the pointer moves in the host element or the user scrolls.
+  | 'move'
+  // The scrollbars are hidden if the pointer leaves the host element or unless the user scrolls.
+  | 'leave';
+
+// The scrollbar click scroll behavior.
+type ScrollbarsClickScrollBehavior = boolean | 'instant';
 };
 ```
 
@@ -588,7 +630,7 @@ const osInstance = OverlayScrollbars(document.body, {});
   | parameter | type | description |
   | :--- | :--- | :--- |
   | newOptions | `PartialOptions` | The new (partial) options which should be applied. |
-  | pure | `boolean / undefined` | Whether the options should be reset before the new options are added. |
+  | pure | `boolean \| undefined` | Whether the options should be reset before the new options are added. |
 
   | returns | description |
   | :--- | :--- |
@@ -601,7 +643,7 @@ const osInstance = OverlayScrollbars(document.body, {});
   | parameter | type | description |
   | :--- | :--- | :--- |
   | eventListeners | `EventListeners` | An object which contains the added listeners. The fields are the event names and the listeners. |
-  | pure | `boolean / undefined` | Whether all already added event listeners should be removed before the new listeners are added. |
+  | pure | `boolean \| undefined` | Whether all already added event listeners should be removed before the new listeners are added. |
 
   | returns | description |
   | :--- | :--- |
@@ -657,7 +699,7 @@ const osInstance = OverlayScrollbars(document.body, {});
 
   | parameter | type | description |
   | :--- | :--- | :--- |
-  | force | `boolean / undefined` |  Whether the update should force the cache to be invalidated. |
+  | force | `boolean \| undefined` |  Whether the update should force the cache to be invalidated. |
 
   | returns | description |
   | :--- | :--- |
@@ -689,7 +731,7 @@ const osInstance = OverlayScrollbars(document.body, {});
 
   | returns | description |
   | :--- | :--- |
-  | `object / undefined` | An object which describes the plugins instance modules instance or `undefined` if no instance was found. |
+  | `object \| undefined` | An object which describes the plugins instance modules instance or `undefined` if no instance was found. |
 
   #### TypeScript 
 
@@ -834,7 +876,7 @@ OverlayScrollbars.plugin(SomePlugin);
 
   | parameter | type | description |
   | :--- | :--- | :--- |
-  | newNonce | `string / undefined` | The nonce attribute for inline styles. |
+  | newNonce | `string \| undefined` | The nonce attribute for inline styles. |
 
   ### `plugin(plugin): object | undefined`
 
@@ -846,7 +888,7 @@ OverlayScrollbars.plugin(SomePlugin);
 
   | returns | description |
   | :--- | :--- |
-  | `object / void` | An object describing the plugin's static module instance or `void` if no instance was found. |
+  | `object \| void` | An object describing the plugin's static module instance or `void` if no instance was found. |
 
   ### `plugin(plugins): (object | void)[]`
 
@@ -858,7 +900,7 @@ OverlayScrollbars.plugin(SomePlugin);
 
   | returns | description |
   | :--- | :--- |
-  | `(object / void)[]` | An array describing the plugins static modules instances or `undefined` if no instance was found. |
+  | `(object \| void)[]` | An array describing the plugins static modules instances or `undefined` if no instance was found. |
 
   #### TypeScript
 
@@ -1050,10 +1092,10 @@ Custom themes can be done in several ways. The easiest and fastest way is to use
 | `.os-scrollbar-rtl` | Indicates a `RTL` direction of the host element the scrollbar belongs to. |
 | `.os-scrollbar-horizontal` | The root element of a horizontal scrollbar. |
 | `.os-scrollbar-vertical` | The root element of a vertical scrollbar. |
-| `.os-scrollbar-handle-interactive` | Indicates that the handle inside the scrollbar is interactive (`scrollbars.dragScroll` is `true`). |
-| `.os-scrollbar-track-interactive` | Indicates that the track inside the scrollbar is interactive (`scrollbars.clickScroll` is `true`). |
-| `.os-scrollbar-track` | The track element. This is the track of the nested handle element. If `scrollbars.clickScroll` is `true` this is the element users can click to change the scroll offset. |
-| `.os-scrollbar-handle` | The handle element. If `scrollbars.dragScroll` is `true` this is the handle users can drag to change the scroll offset. |
+| `.os-scrollbar-handle-interactive` | Indicates that the handle inside the scrollbar is interactive (`scrollbars.dragScroll` is not `false`). |
+| `.os-scrollbar-track-interactive` | Indicates that the track inside the scrollbar is interactive (`scrollbars.clickScroll` is not `false`). |
+| `.os-scrollbar-track` | The track element. This is the track of the nested handle element. If `scrollbars.clickScroll` is not `false` this is the element users can click to change the scroll offset. |
+| `.os-scrollbar-handle` | The handle element. If `scrollbars.dragScroll` is not `false` this is the handle users can drag to change the scroll offset. |
 
   If you create your own theme, please only use the classes listed above. All other classes are modifier classes used to change visibility, alignment and pointer-events of the scrollbars.
 
diff --git a/packages/overlayscrollbars/package.json b/packages/overlayscrollbars/package.json
@@ -1,7 +1,7 @@
 {
   "name": "overlayscrollbars",
   "private": true,
-  "version": "2.9.2",
+  "version": "2.10.0",
   "description": "A javascript scrollbar plugin that hides the native scrollbars, provides custom styleable overlay scrollbars, and preserves the native functionality and feel.",
   "author": "Rene Haas | KingSora",
   "license": "MIT",
diff --git a/packages/overlayscrollbars/src/options.ts b/packages/overlayscrollbars/src/options.ts
@@ -137,6 +137,11 @@ export type ScrollbarsAutoHideBehavior =
   /** The scrollbars are hidden if the pointer leaves the host element or unless the user scrolls. */
   | 'leave';
 
+/**
+ * The scrollbar click scroll behavior.
+ */
+export type ScrollbarsClickScrollBehavior = boolean | 'instant';
+
 /**
  * The options of a OverlayScrollbars instance.
  */
@@ -198,7 +203,7 @@ export type Options = {
     /** Whether it is possible to drag the handle of a scrollbar to scroll the viewport. */
     dragScroll: boolean;
     /** Whether it is possible to click the track of a scrollbar to scroll the viewport. */
-    clickScroll: boolean;
+    clickScroll: ScrollbarsClickScrollBehavior;
     /**
      * An array of pointer types which shall be supported.
      * Common pointer types are: `mouse`, `pen` and `touch`.
diff --git a/packages/overlayscrollbars/src/plugins/optionsValidationPlugin/optionsValidationPlugin.ts b/packages/overlayscrollbars/src/plugins/optionsValidationPlugin/optionsValidationPlugin.ts
@@ -4,6 +4,7 @@ import type {
   OverflowBehavior,
   ScrollbarsVisibilityBehavior,
   ScrollbarsAutoHideBehavior,
+  ScrollbarsClickScrollBehavior,
 } from '~/options';
 import type { OptionsTemplate, OptionsTemplateValue } from './validation';
 import type { StaticPlugin } from '~/plugins';
@@ -26,9 +27,10 @@ export const OptionsValidationPlugin = /* @__PURE__ */ (() => ({
         'visible hidden auto';
       const scrollbarsAutoHideAllowedValues: OptionsTemplateValue<ScrollbarsAutoHideBehavior> =
         'never scroll leavemove';
+      const scrollbarsClickScrollAllowedValues: OptionsTemplateValue<ScrollbarsClickScrollBehavior> =
+        [booleanAllowedValues, oTypes.string];
 
       const optionsTemplate: OptionsTemplate<Options> = {
-        // resize: resizeAllowedValues, // none || both  || horizontal || vertical || n || b ||
         paddingAbsolute: booleanAllowedValues, // true || false
         showNativeOverlaidScrollbars: booleanAllowedValues, // true || false
         update: {
@@ -38,17 +40,17 @@ export const OptionsValidationPlugin = /* @__PURE__ */ (() => ({
           ignoreMutation: [oTypes.function, oTypes.null], // function || null
         },
         overflow: {
-          x: overflowAllowedValues, // visible-hidden  || visible-scroll || hidden || scrol
-          y: overflowAllowedValues, // visible-hidden  || visible-scroll || hidden || scrol
+          x: overflowAllowedValues, // visible-hidden  || visible-scroll || hidden || scroll
+          y: overflowAllowedValues, // visible-hidden  || visible-scroll || hidden || scroll
         },
         scrollbars: {
           theme: [oTypes.string, oTypes.null], // string || null
-          visibility: scrollbarsVisibilityAllowedValues, // visible || hidden || auto || v ||
+          visibility: scrollbarsVisibilityAllowedValues, // visible || hidden || auto
           autoHide: scrollbarsAutoHideAllowedValues, // never || scroll || leave || move ||
           autoHideDelay: numberAllowedValues, // number
           autoHideSuspend: booleanAllowedValues, // true || false
           dragScroll: booleanAllowedValues, // true || false
-          clickScroll: booleanAllowedValues, // true || false
+          clickScroll: scrollbarsClickScrollAllowedValues, // true || false || instant
           pointers: [oTypes.array, oTypes.null], // string array
         },
         /*
diff --git a/packages/overlayscrollbars/src/setups/scrollbarsSetup/scrollbarsSetup.events.ts b/packages/overlayscrollbars/src/setups/scrollbarsSetup/scrollbarsSetup.events.ts
diff --git a/packages/overlayscrollbars/src/setups/scrollbarsSetup/scrollbarsSetup.ts b/packages/overlayscrollbars/src/setups/scrollbarsSetup/scrollbarsSetup.ts
diff --git a/website/mdx/README.mdx b/website/mdx/README.mdx

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "overlayscrollbars",`
`3`	`3`	`"private": true,`
`4`		`- "version": "2.9.2",`
	`4`	`+ "version": "2.10.0",`
`5`	`5`	`"description": "A javascript scrollbar plugin that hides the native scrollbars, provides custom styleable overlay scrollbars, and preserves the native functionality and feel.",`
`6`	`6`	`"author": "Rene Haas \| KingSora",`
`7`	`7`	`"license": "MIT",`