Skip to content

Commit

Permalink
v2.10.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@KingSora
KingSora committed Jul 29, 2024
1 parent b78db4f commit b7a96af
Show file tree
Hide file tree
Showing 9 changed files with 217 additions and 74 deletions.
74 changes: 58 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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';
};
```

Expand Down Expand Up @@ -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 |
| :--- | :--- |
Expand All @@ -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 |
| :--- | :--- |
Expand Down Expand Up @@ -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 |
| :--- | :--- |
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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`

Expand All @@ -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)[]`

Expand All @@ -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

Expand Down Expand Up @@ -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.

Expand Down
10 changes: 10 additions & 0 deletions packages/overlayscrollbars/CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down
74 changes: 58 additions & 16 deletions packages/overlayscrollbars/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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';
};
```

Expand Down Expand Up @@ -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 |
| :--- | :--- |
Expand All @@ -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 |
| :--- | :--- |
Expand Down Expand Up @@ -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 |
| :--- | :--- |
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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`

Expand All @@ -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)[]`

Expand All @@ -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

Expand Down Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion packages/overlayscrollbars/package.json
View file
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
7 changes: 6 additions & 1 deletion packages/overlayscrollbars/src/options.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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`.
Expand Down
12 changes: 7 additions & 5 deletions packages/overlayscrollbars/src/plugins/optionsValidationPlugin/optionsValidationPlugin.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import type {
OverflowBehavior,
ScrollbarsVisibilityBehavior,
ScrollbarsAutoHideBehavior,
ScrollbarsClickScrollBehavior,
} from '~/options';
import type { OptionsTemplate, OptionsTemplateValue } from './validation';
import type { StaticPlugin } from '~/plugins';
Expand All @@ -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: {
Expand All @@ -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
},
/*
Expand Down
Loading

0 comments on commit b7a96af

Please sign in to comment.