mirrors/OverlayScrollbars
2
0
Fork 0
mirror of https://github.com/tenrok/OverlayScrollbars.git synced 2026-05-24 19:24:08 +03:00
Code Issues Packages Projects Releases Wiki Activity

improve readme and exports

Browse Source
This commit is contained in:
Rene Haas
2022-09-14 13:07:40 +02:00
parent c05e9f1d3a
commit 0a1174cc59
16 changed files with 112 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+42 -12
View File
@@ -64,7 +64,7 @@ Embedd OverlayScrollbars manually in your HTML:
## Initialization
> __Note__ During initialization its expected that the <b>CSS file is loaded and parsed</b> by the browser.
> __Note__: During initialization its expected that the <b>CSS file is loaded and parsed</b> by the browser.
You can initialize either directly with an `Element` or with an `Object` where you have more control over the initialization process.
@@ -75,7 +75,7 @@ const osInstance = OverlayScrollbars(document.querySelector('#myElement'), {});
<details><summary><h6>Initialization with an Object</h6></summary>
> __Note__ For now please refer to the <b>TypeScript definitions</b> for a more detailed description of all possibilities.
> __Note__: For now please refer to the <b>TypeScript definitions</b> for a more detailed description of all possibilities.
The only required field is the `target` field. This is the field to which the plugin is applied to.
If you use the object initialization only with the `target` field, the outcome is equivalent to the element initialization:
@@ -200,7 +200,7 @@ An array of tuples. The first value in the tuple is an `selector` and the second
| :--- | :--- |
| `[number, number] \| number \| null` | `[0, 33]` |
> __Note__ If 0 is used for the timeout, `requestAnimationFrame` instead of `setTimeout` is used for the debounce.
> __Note__: If 0 is used for the timeout, `requestAnimationFrame` instead of `setTimeout` is used for the debounce.
Debounces the `MutationObserver` which tracks changes to the content. If a **tuple** is passed, the first value is the timeout and second is the max wait. If only a **number** is passed you specify only the timeout and there is no max wait. With **null** there is no debounce. **Usefull to fine-tune performance.**
@@ -210,7 +210,7 @@ Debounces the `MutationObserver` which tracks changes to the content. If a **tup
| :--- | :--- |
| `string[] \| null` | `null` |
> __Note__ There is a base array of attributes that the `MutationObserver` always observes, even if this option is `null`.
> __Note__: There is a base array of attributes that the `MutationObserver` always observes, even if this option is `null`.
An array of additional attributes that the `MutationObserver` should observe for the content.
@@ -228,7 +228,7 @@ A function which receives a [`MutationRecord`](https://developer.mozilla.org/en-
| :--- | :--- |
| `string` | `'scroll'` |
> __Note__ Valid values are: `'hidden'`, `'scroll'`, `'visible'`, `'visible-hidden'` and `'visible-scroll'`.
> __Note__: Valid values are: `'hidden'`, `'scroll'`, `'visible'`, `'visible-hidden'` and `'visible-scroll'`.
The overflow behavior for the horizontal (x) axis.
@@ -238,7 +238,7 @@ The overflow behavior for the horizontal (x) axis.
| :--- | :--- |
| `string` | `'scroll'` |
> __Note__ Valid values are: `'hidden'`, `'scroll'`, `'visible'`, `'visible-hidden'` and `'visible-scroll'`.
> __Note__: Valid values are: `'hidden'`, `'scroll'`, `'visible'`, `'visible-hidden'` and `'visible-scroll'`.
The overflow behavior for the vertical (y) axis.
@@ -256,7 +256,7 @@ Applies the specified theme (classname) to the scrollbars.
| :--- | :--- |
| `string` | `'auto'` |
> __Note__ Valid values are: `'visible'`, `'hidden'`, and `'auto'`.
> __Note__: Valid values are: `'visible'`, `'hidden'`, and `'auto'`.
The base visibility of the scrollbars.
@@ -266,7 +266,7 @@ The base visibility of the scrollbars.
| :--- | :--- |
| `string` | `'never'` |
> __Note__ Valid values are: `'never'`, `'scroll'`, `'leave'` and `'move'`.
> __Note__: Valid values are: `'never'`, `'scroll'`, `'leave'` and `'move'`.
The possibility to hide visible scrollbars automatically after a certain user action.
@@ -317,7 +317,7 @@ OverlayScrollbars(document.querySelector('#myElement'), {}, {
<details><summary><h6>Events in depth</h6></summary>
> __Note__ Every event receives the `instance` from which it was fired as the first argument. Always.
> __Note__: Every event receives the `instance` from which it was fired as the first argument. Always.
### `initialized`
@@ -334,7 +334,7 @@ Is fired after all generated elements, observers and events were appended to the
| `instance` | The instance which fired the event. |
| `onUpdatedArgs` | An `object` which describes the update in detail. |
> __Note__ If an update was triggered but nothing changed, the event won't be fired.
> __Note__: If an update was triggered but nothing changed, the event won't be fired.
Is fired after the instace was updated.
@@ -351,7 +351,7 @@ Is fired after all generated elements, observers and events were removed from th
## Instance Methods
> __Note__ For now please refer to the <b>TypeScript definitions</b> for a more detailed description.
> __Note__: For now please refer to the <b>TypeScript definitions</b> for a more detailed description.
```ts
interface OverlayScrollbars {
@@ -376,7 +376,7 @@ interface OverlayScrollbars {
## Static Methods
> __Note__ For now please refer to the <b>TypeScript definitions</b> for a more detailed description.
> __Note__: For now please refer to the <b>TypeScript definitions</b> for a more detailed description.
```ts
interface OverlayScrollbarsStatic {
@@ -393,6 +393,36 @@ interface OverlayScrollbarsStatic {
}
```
## Plugins
Everything thats considered not core functionality or old browser compatibility is exposed via a plugin. This is done because all unused plugins are treeshaken and thus won't end up in your final bundle. OverlayScrollbars comes with the following plugins:
- **ScrollbarsHidingPlugin**: Is needed for old browsers which aren't supporting nativ scrollbar styling features. [You can find the list of browsers where you need this plugin here](https://caniuse.com/?search=scrollbar%20styling) (note that even though `iOS Safari >= 14` is marked as unsupported you only need this plugin for `iOS < 7.1`).
- **SizeObserverPlugin**: Is needed for old browsers which aren't supporting the `ResizeObserver` api. [You can find the list of browsers where you need this plugin here](https://caniuse.com/?search=ResizeObserver)
- **ClickScrollPlugin**: If you want to use the option `scrollbars: { clickScroll: true }`.
#### Consuming Plugins
You can consume plugins like:
```ts
import {
OverlayScrollbars,
ScrollbarsHidingPlugin,
SizeObserverPlugin,
ClickScrollPlugin
} from 'overlayscrollbars';
// single plugin
OverlayScrollbars.plugin(ScrollbarsHidingPlugin);
// multiple plugins
OverlayScrollbars.plugin([SizeObserverPlugin, ClickScrollPlugin]);
```
#### Writing Plugins
You can write and publish your own Plugins. This section is a work in progress.
## Sponsors
<table>
<tr>
packages/overlayscrollbars/README.md
+42 -12
View File
@@ -64,7 +64,7 @@ Embedd OverlayScrollbars manually in your HTML:
## Initialization
> __Note__ During initialization its expected that the <b>CSS file is loaded and parsed</b> by the browser.
> __Note__: During initialization its expected that the <b>CSS file is loaded and parsed</b> by the browser.
You can initialize either directly with an `Element` or with an `Object` where you have more control over the initialization process.
@@ -75,7 +75,7 @@ const osInstance = OverlayScrollbars(document.querySelector('#myElement'), {});
<details><summary><h6>Initialization with an Object</h6></summary>
> __Note__ For now please refer to the <b>TypeScript definitions</b> for a more detailed description of all possibilities.
> __Note__: For now please refer to the <b>TypeScript definitions</b> for a more detailed description of all possibilities.
The only required field is the `target` field. This is the field to which the plugin is applied to.
If you use the object initialization only with the `target` field, the outcome is equivalent to the element initialization:
@@ -200,7 +200,7 @@ An array of tuples. The first value in the tuple is an `selector` and the second
| :--- | :--- |
| `[number, number] \| number \| null` | `[0, 33]` |
> __Note__ If 0 is used for the timeout, `requestAnimationFrame` instead of `setTimeout` is used for the debounce.
> __Note__: If 0 is used for the timeout, `requestAnimationFrame` instead of `setTimeout` is used for the debounce.
Debounces the `MutationObserver` which tracks changes to the content. If a **tuple** is passed, the first value is the timeout and second is the max wait. If only a **number** is passed you specify only the timeout and there is no max wait. With **null** there is no debounce. **Usefull to fine-tune performance.**
@@ -210,7 +210,7 @@ Debounces the `MutationObserver` which tracks changes to the content. If a **tup
| :--- | :--- |
| `string[] \| null` | `null` |
> __Note__ There is a base array of attributes that the `MutationObserver` always observes, even if this option is `null`.
> __Note__: There is a base array of attributes that the `MutationObserver` always observes, even if this option is `null`.
An array of additional attributes that the `MutationObserver` should observe for the content.
@@ -228,7 +228,7 @@ A function which receives a [`MutationRecord`](https://developer.mozilla.org/en-
| :--- | :--- |
| `string` | `'scroll'` |
> __Note__ Valid values are: `'hidden'`, `'scroll'`, `'visible'`, `'visible-hidden'` and `'visible-scroll'`.
> __Note__: Valid values are: `'hidden'`, `'scroll'`, `'visible'`, `'visible-hidden'` and `'visible-scroll'`.
The overflow behavior for the horizontal (x) axis.
@@ -238,7 +238,7 @@ The overflow behavior for the horizontal (x) axis.
| :--- | :--- |
| `string` | `'scroll'` |
> __Note__ Valid values are: `'hidden'`, `'scroll'`, `'visible'`, `'visible-hidden'` and `'visible-scroll'`.
> __Note__: Valid values are: `'hidden'`, `'scroll'`, `'visible'`, `'visible-hidden'` and `'visible-scroll'`.
The overflow behavior for the vertical (y) axis.
@@ -256,7 +256,7 @@ Applies the specified theme (classname) to the scrollbars.
| :--- | :--- |
| `string` | `'auto'` |
> __Note__ Valid values are: `'visible'`, `'hidden'`, and `'auto'`.
> __Note__: Valid values are: `'visible'`, `'hidden'`, and `'auto'`.
The base visibility of the scrollbars.
@@ -266,7 +266,7 @@ The base visibility of the scrollbars.
| :--- | :--- |
| `string` | `'never'` |
> __Note__ Valid values are: `'never'`, `'scroll'`, `'leave'` and `'move'`.
> __Note__: Valid values are: `'never'`, `'scroll'`, `'leave'` and `'move'`.
The possibility to hide visible scrollbars automatically after a certain user action.
@@ -317,7 +317,7 @@ OverlayScrollbars(document.querySelector('#myElement'), {}, {
<details><summary><h6>Events in depth</h6></summary>
> __Note__ Every event receives the `instance` from which it was fired as the first argument. Always.
> __Note__: Every event receives the `instance` from which it was fired as the first argument. Always.
### `initialized`
@@ -334,7 +334,7 @@ Is fired after all generated elements, observers and events were appended to the
| `instance` | The instance which fired the event. |
| `onUpdatedArgs` | An `object` which describes the update in detail. |
> __Note__ If an update was triggered but nothing changed, the event won't be fired.
> __Note__: If an update was triggered but nothing changed, the event won't be fired.
Is fired after the instace was updated.
@@ -351,7 +351,7 @@ Is fired after all generated elements, observers and events were removed from th
## Instance Methods
> __Note__ For now please refer to the <b>TypeScript definitions</b> for a more detailed description.
> __Note__: For now please refer to the <b>TypeScript definitions</b> for a more detailed description.
```ts
interface OverlayScrollbars {
@@ -376,7 +376,7 @@ interface OverlayScrollbars {
## Static Methods
> __Note__ For now please refer to the <b>TypeScript definitions</b> for a more detailed description.
> __Note__: For now please refer to the <b>TypeScript definitions</b> for a more detailed description.
```ts
interface OverlayScrollbarsStatic {
@@ -393,6 +393,36 @@ interface OverlayScrollbarsStatic {
}
```
## Plugins
Everything thats considered not core functionality or old browser compatibility is exposed via a plugin. This is done because all unused plugins are treeshaken and thus won't end up in your final bundle. OverlayScrollbars comes with the following plugins:
- **ScrollbarsHidingPlugin**: Is needed for old browsers which aren't supporting nativ scrollbar styling features. [You can find the list of browsers where you need this plugin here](https://caniuse.com/?search=scrollbar%20styling) (note that even though `iOS Safari >= 14` is marked as unsupported you only need this plugin for `iOS < 7.1`).
- **SizeObserverPlugin**: Is needed for old browsers which aren't supporting the `ResizeObserver` api. [You can find the list of browsers where you need this plugin here](https://caniuse.com/?search=ResizeObserver)
- **ClickScrollPlugin**: If you want to use the option `scrollbars: { clickScroll: true }`.
#### Consuming Plugins
You can consume plugins like:
```ts
import {
OverlayScrollbars,
ScrollbarsHidingPlugin,
SizeObserverPlugin,
ClickScrollPlugin
} from 'overlayscrollbars';
// single plugin
OverlayScrollbars.plugin(ScrollbarsHidingPlugin);
// multiple plugins
OverlayScrollbars.plugin([SizeObserverPlugin, ClickScrollPlugin]);
```
#### Writing Plugins
You can write and publish your own Plugins. This section is a work in progress.
## Sponsors
<table>
<tr>
packages/overlayscrollbars/src/index.ts
+1 -1
View File
@@ -1,7 +1,7 @@
import 'index.scss';
export { OverlayScrollbars } from 'overlayscrollbars';
export { scrollbarsHidingPlugin, sizeObserverPlugin } from 'plugins';
export { ScrollbarsHidingPlugin, SizeObserverPlugin, ClickScrollPlugin } from 'plugins';
export type {
Options,
packages/overlayscrollbars/src/plugins/clickScrollPlugin/clickScrollPlugin.ts
+1 -1
View File
@@ -13,7 +13,7 @@ export type ClickScrollPluginInstance = {
export const clickScrollPluginName = '__osClickScrollPlugin';
export const clickScrollPlugin: Plugin<ClickScrollPluginInstance> = /* @__PURE__ */ (() => ({
export const ClickScrollPlugin: Plugin<ClickScrollPluginInstance> = /* @__PURE__ */ (() => ({
[clickScrollPluginName]: {
_: (
moveHandleRelative,
packages/overlayscrollbars/src/plugins/optionsValidationPlugin/optionsValidationPlugin.ts
+1 -1
View File
@@ -61,7 +61,7 @@ export type OptionsValidationPluginInstance = {
export const optionsValidationPluginName = '__osOptionsValidationPlugin';
export const optionsValidationPlugin: Plugin<OptionsValidationPluginInstance> =
export const OptionsValidationPlugin: Plugin<OptionsValidationPluginInstance> =
/* @__PURE__ */ (() => ({
[optionsValidationPluginName]: {
_: (options: DeepPartial<Options>, doWriteErrors?: boolean) => {
packages/overlayscrollbars/src/plugins/scrollbarsHidingPlugin/scrollbarsHidingPlugin.ts
+1 -1
View File
@@ -79,7 +79,7 @@ const diffBiggerThanOne = (valOne: number, valTwo: number): boolean => {
export const scrollbarsHidingPluginName = '__osScrollbarsHidingPlugin';
export const scrollbarsHidingPlugin: Plugin<ScrollbarsHidingPluginInstance> =
export const ScrollbarsHidingPlugin: Plugin<ScrollbarsHidingPluginInstance> =
/* @__PURE__ */ (() => ({
[scrollbarsHidingPluginName]: {
_createUniqueViewportArrangeElement: (env: InternalEnvironment) => {
packages/overlayscrollbars/src/plugins/sizeObserverPlugin/sizeObserverPlugin.ts
+1 -1
View File
@@ -32,7 +32,7 @@ const scrollAmount = 3333333;
const scrollEventName = 'scroll';
export const sizeObserverPluginName = '__osSizeObserverPlugin';
export const sizeObserverPlugin: Plugin<SizeObserverPluginInstance> = /* @__PURE__ */ (() => ({
export const SizeObserverPlugin: Plugin<SizeObserverPluginInstance> = /* @__PURE__ */ (() => ({
[sizeObserverPluginName]: {
_: (listenerElement, onSizeChangedCallback, observeAppearChange) => {
const observerElementChildren = createDOM(
packages/overlayscrollbars/tests/jest-jsdom/environment.test.ts
+3 -3
View File
@@ -2,7 +2,7 @@ import { DeepPartial } from 'typings';
import { defaultOptions, Options } from 'options';
import { Initialization } from 'initialization';
import { getEnvironment } from 'environment';
import { scrollbarsHidingPlugin, scrollbarsHidingPluginName } from 'plugins';
import { ScrollbarsHidingPlugin, scrollbarsHidingPluginName } from 'plugins';
const defaultInitialization = {
elements: {
@@ -145,7 +145,7 @@ describe('environment', () => {
test('with scrollbarsHidingPlugin registered before environment was created', async () => {
const { getPlugins } = await import('plugins');
(getPlugins as jest.Mock).mockImplementation(() => ({
[scrollbarsHidingPluginName]: scrollbarsHidingPlugin[scrollbarsHidingPluginName],
[scrollbarsHidingPluginName]: ScrollbarsHidingPlugin[scrollbarsHidingPluginName],
}));
const { _addListener } = getEnv();
@@ -165,7 +165,7 @@ describe('environment', () => {
const { getPlugins } = await import('plugins');
(getPlugins as jest.Mock).mockImplementation(() => ({
[scrollbarsHidingPluginName]: scrollbarsHidingPlugin[scrollbarsHidingPluginName],
[scrollbarsHidingPluginName]: ScrollbarsHidingPlugin[scrollbarsHidingPluginName],
}));
window.dispatchEvent(new Event('resize'));
packages/overlayscrollbars/tests/jest-jsdom/observers/sizeObserver.test.ts
+2 -2
View File
@@ -1,5 +1,5 @@
import { createSizeObserver as originalCreateSizeObserver } from 'observers';
import { sizeObserverPlugin, sizeObserverPluginName } from 'plugins';
import { SizeObserverPlugin, sizeObserverPluginName } from 'plugins';
let createSizeObserver = originalCreateSizeObserver;
@@ -59,7 +59,7 @@ describe('createSizeObserver', () => {
describe('with sizeObserverPlugin', () => {
const mockSizeObserverPlugin = jest.fn((...a) => [
// @ts-ignore
sizeObserverPlugin[sizeObserverPluginName]._(...a),
SizeObserverPlugin[sizeObserverPluginName]._(...a),
]);
beforeEach(() => {
packages/overlayscrollbars/tests/jest-jsdom/overlayscrollbars.test.ts
+2 -2
View File
@@ -1,7 +1,7 @@
import { DeepPartial } from 'typings';
import { defaultOptions, Options } from 'options';
import { assignDeep } from 'support';
import { optionsValidationPlugin } from 'plugins';
import { OptionsValidationPlugin } from 'plugins';
import { OverlayScrollbars as originalOverlayScrollbars } from '../../src/overlayscrollbars';
const bodyElm = document.body;
@@ -242,7 +242,7 @@ describe('overlayscrollbars', () => {
describe(`${withValidationPlugin ? 'with' : 'without'} optionsValidationPlugin`, () => {
beforeEach(() => {
if (withValidationPlugin) {
OverlayScrollbars.plugin(optionsValidationPlugin);
OverlayScrollbars.plugin(OptionsValidationPlugin);
}
});
packages/overlayscrollbars/tests/jest-jsdom/plugins/optionsValidation/optionsValidation.test.ts
+3 -3
View File
@@ -1,12 +1,12 @@
import { defaultOptions } from 'options';
import {
optionsValidationPlugin,
OptionsValidationPlugin,
optionsValidationPluginName,
} from 'plugins/optionsValidationPlugin';
const getValidationFn = () => {
const name = Object.keys(optionsValidationPlugin)[0];
const instance = optionsValidationPlugin[name];
const name = Object.keys(OptionsValidationPlugin)[0];
const instance = OptionsValidationPlugin[name];
const validationFn = instance._;
expect(name).toBe(optionsValidationPluginName);
packages/overlayscrollbars/tests/jest-jsdom/setups/structureSetup/structureSetup.elements.test.ts
+2 -2
View File
@@ -10,7 +10,7 @@ import {
createStructureSetupElements,
StructureSetupElementsObj,
} from 'setups/structureSetup/structureSetup.elements';
import { addPlugin, scrollbarsHidingPlugin } from 'plugins';
import { addPlugin, ScrollbarsHidingPlugin } from 'plugins';
import type {
Initialization,
InitializationTarget,
@@ -21,7 +21,7 @@ jest.mock('environment', () => ({
getEnvironment: jest.fn(),
}));
addPlugin(scrollbarsHidingPlugin);
addPlugin(ScrollbarsHidingPlugin);
interface StructureSetupElementsProxy {
input: InitializationTarget;
packages/overlayscrollbars/tests/playwright/observers/sizeObserver/index.browser.ts
+2 -2
View File
@@ -11,11 +11,11 @@ import {
waitForOrFailTest,
} from '@~local/browser-testing';
import { hasDimensions, offsetSize, WH, style } from 'support';
import { addPlugin, sizeObserverPlugin } from 'plugins';
import { addPlugin, SizeObserverPlugin } from 'plugins';
import { createSizeObserver } from 'observers';
if (!window.ResizeObserver) {
addPlugin(sizeObserverPlugin);
addPlugin(SizeObserverPlugin);
}
let sizeIterations = 0;
packages/overlayscrollbars/tests/playwright/observers/trinsicObserver/index.browser.ts
+2 -2
View File
@@ -12,10 +12,10 @@ import {
} from '@~local/browser-testing';
import { offsetSize } from 'support';
import { createTrinsicObserver } from 'observers';
import { addPlugin, sizeObserverPlugin } from 'plugins';
import { addPlugin, SizeObserverPlugin } from 'plugins';
if (!window.ResizeObserver) {
addPlugin(sizeObserverPlugin);
addPlugin(SizeObserverPlugin);
}
let heightIntrinsic: boolean | undefined;
packages/overlayscrollbars/tests/playwright/setups/structureSetup/nesting/index.browser.ts
+3 -3
View File
@@ -4,13 +4,13 @@ import should from 'should';
import { timeout, setTestResult, waitForOrFailTest, resize } from '@~local/browser-testing';
import { OverlayScrollbars } from 'overlayscrollbars';
import { addClass, each, isArray, removeAttr, style } from 'support';
import { addPlugin, scrollbarsHidingPlugin, sizeObserverPlugin } from 'plugins';
import { addPlugin, ScrollbarsHidingPlugin, SizeObserverPlugin } from 'plugins';
if (!window.ResizeObserver) {
addPlugin(sizeObserverPlugin);
addPlugin(SizeObserverPlugin);
}
if (!OverlayScrollbars.env().scrollbarsHiding) {
addPlugin(scrollbarsHidingPlugin);
addPlugin(ScrollbarsHidingPlugin);
}
// @ts-ignore
packages/overlayscrollbars/tests/playwright/setups/structureSetup/update/index.browser.ts
+4 -4
View File
@@ -32,15 +32,15 @@ import {
} from 'support';
import { Options } from 'options';
import { DeepPartial } from 'typings';
import { addPlugin, scrollbarsHidingPlugin, sizeObserverPlugin, clickScrollPlugin } from 'plugins';
import { addPlugin, ScrollbarsHidingPlugin, SizeObserverPlugin, ClickScrollPlugin } from 'plugins';
addPlugin(clickScrollPlugin);
addPlugin(ClickScrollPlugin);
if (!window.ResizeObserver) {
addPlugin(sizeObserverPlugin);
addPlugin(SizeObserverPlugin);
}
if (!OverlayScrollbars.env().scrollbarsHiding) {
addPlugin(scrollbarsHidingPlugin);
addPlugin(ScrollbarsHidingPlugin);
}
// @ts-ignore