improve api, readmes, overlayscrollbars-react and finish overlayscrollbars-vue

packages/overlayscrollbars-react/test/OverlayScrollbarsComponent.test.tsx

@@ -9,29 +9,46 @@ import type { OverlayScrollbarsComponentRef } from '~/overlayscrollbars-react';
 
 describe('OverlayScrollbarsComponent', () => {
   describe('correct rendering', () => {
-    test('correct root element', () => {
+    test('correct root element with instance', () => {
       const elementA = 'code';
       const elementB = 'span';
+      let osInstance;
       const { container, rerender } = render(<OverlayScrollbarsComponent />);
 
       expect(container).not.toBeEmptyDOMElement();
       expect(container.querySelector('div')).toBe(container.firstElementChild); // default is div
 
+      expect(OverlayScrollbars.valid(osInstance)).toBe(false);
+      osInstance = OverlayScrollbars(container.firstElementChild as HTMLElement);
+      expect(osInstance).toBeDefined();
+      expect(OverlayScrollbars.valid(osInstance)).toBe(true);
+
       rerender(<OverlayScrollbarsComponent element={elementA} />);
       expect(container.querySelector(elementA)).toBe(container.firstElementChild);
 
+      expect(OverlayScrollbars.valid(osInstance)).toBe(false); // prev instance is destroyed
+      osInstance = OverlayScrollbars(container.firstElementChild as HTMLElement);
+      expect(osInstance).toBeDefined();
+      expect(OverlayScrollbars.valid(osInstance)).toBe(true);
+
       rerender(<OverlayScrollbarsComponent element={elementB} />);
       expect(container.querySelector(elementB)).toBe(container.firstElementChild);
+
+      expect(OverlayScrollbars.valid(osInstance)).toBe(false); // prev instance is destroyed
+      osInstance = OverlayScrollbars(container.firstElementChild as HTMLElement);
+      expect(osInstance).toBeDefined();
+      expect(OverlayScrollbars.valid(osInstance)).toBe(true);
     });
 
     test('children', () => {
-      render(
+      const { container } = render(
         <OverlayScrollbarsComponent>
           hello <span>react</span>
         </OverlayScrollbarsComponent>
       );
       expect(screen.getByText(/hello/)).toBeInTheDocument();
       expect(screen.getByText(/react/)).toBeInTheDocument();
+      expect(screen.getByText(/react/).parentElement).not.toBe(container.firstElementChild);
     });
 
     test('dynamic children', async () => {
@@ -112,26 +129,61 @@ describe('OverlayScrollbarsComponent', () => {
         ref={ref}
       />
     );
+    const instance = ref.current!.instance()!;
 
-    const opts = ref.current!.instance()!.options();
+    const opts = instance.options();
     expect(opts.paddingAbsolute).toBe(true);
     expect(opts.overflow.y).toBe('hidden');
 
     rerender(<OverlayScrollbarsComponent options={{ overflow: { x: 'hidden' } }} ref={ref} />);
 
-    const newOpts = ref.current!.instance()!.options()!;
+    const newOpts = instance.options();
     expect(newOpts.paddingAbsolute).toBe(false); //switches back to default because its not specified in the new options
-    expect(newOpts.overflow.y).toBe('scroll'); //switches back to default because its not specified in the new options
     expect(newOpts.overflow.x).toBe('hidden');
+    expect(newOpts.overflow.y).toBe('scroll'); //switches back to default because its not specified in the new options
+
+    // instance didn't change
+    expect(instance).toBe(ref.current!.instance());
+
+    rerender(
+      <OverlayScrollbarsComponent
+        element="span"
+        options={{ overflow: { x: 'hidden', y: 'hidden' } }}
+        ref={ref as any as RefObject<OverlayScrollbarsComponentRef<'span'>>}
+      />
+    );
+
+    const newElementInstance = ref.current!.instance()!;
+    const newElementNewOpts = newElementInstance.options();
+    expect(newElementInstance).not.toBe(instance);
+    expect(newElementNewOpts.paddingAbsolute).toBe(false);
+    expect(newElementNewOpts.overflow.x).toBe('hidden');
+    expect(newElementNewOpts.overflow.y).toBe('hidden');
+
+    // reset options with `undefined`, `null`, `false` or `{}`
+    rerender(
+      <OverlayScrollbarsComponent
+        element="span"
+        options={undefined}
+        ref={ref as any as RefObject<OverlayScrollbarsComponentRef<'span'>>}
+      />
+    );
+
+    const resetOpts = newElementInstance.options();
+    expect(newElementInstance).toBe(ref.current!.instance());
+    expect(resetOpts.paddingAbsolute).toBe(false);
+    expect(resetOpts.overflow.x).toBe('scroll');
+    expect(resetOpts.overflow.y).toBe('scroll');
   });
 
   test('events', () => {
-    const ref: RefObject<OverlayScrollbarsComponentRef> = { current: null };
     const onUpdatedInitial = vitest.fn();
     const onUpdated = vitest.fn();
+    const ref: RefObject<OverlayScrollbarsComponentRef> = { current: null };
     const { rerender } = render(
       <OverlayScrollbarsComponent events={{ updated: onUpdatedInitial }} ref={ref} />
     );
+    const instance = ref.current!.instance()!;
 
     expect(onUpdatedInitial).toHaveBeenCalledTimes(1);
 
@@ -139,7 +191,7 @@ describe('OverlayScrollbarsComponent', () => {
 
     expect(onUpdated).not.toHaveBeenCalled();
 
-    ref.current!.instance()!.update(true);
+    instance.update(true);
     expect(onUpdatedInitial).toHaveBeenCalledTimes(1);
     expect(onUpdated).toHaveBeenCalledTimes(1);
 
@@ -147,60 +199,44 @@ describe('OverlayScrollbarsComponent', () => {
       <OverlayScrollbarsComponent events={{ updated: [onUpdated, onUpdatedInitial] }} ref={ref} />
     );
 
-    ref.current!.instance()!.update(true);
+    instance.update(true);
     expect(onUpdatedInitial).toHaveBeenCalledTimes(2);
     expect(onUpdated).toHaveBeenCalledTimes(2);
 
     // unregister works with `[]`, `null` or `undefined`
     rerender(<OverlayScrollbarsComponent events={{ updated: null }} ref={ref} />);
 
-    ref.current!.instance()!.update(true);
+    instance.update(true);
     expect(onUpdatedInitial).toHaveBeenCalledTimes(2);
     expect(onUpdated).toHaveBeenCalledTimes(2);
-  });
 
-  test('events', () => {
-    const ref: RefObject<OverlayScrollbarsComponentRef> = { current: null };
-    const onUpdatedInitial = vitest.fn();
-    const onUpdated = vitest.fn();
-    const { rerender } = render(
-      <OverlayScrollbarsComponent events={{ updated: onUpdatedInitial }} ref={ref} />
-    );
-
-    expect(onUpdatedInitial).toHaveBeenCalledTimes(1);
-
-    rerender(<OverlayScrollbarsComponent events={{ updated: onUpdated }} ref={ref} />);
-
-    expect(onUpdated).not.toHaveBeenCalled();
-
-    ref.current!.instance()!.update(true);
-    expect(onUpdatedInitial).toHaveBeenCalledTimes(1);
-    expect(onUpdated).toHaveBeenCalledTimes(1);
-
-    rerender(<OverlayScrollbarsComponent events={{ updated: onUpdatedInitial }} ref={ref} />);
-
-    ref.current!.instance()!.update(true);
-    expect(onUpdatedInitial).toHaveBeenCalledTimes(2);
-    expect(onUpdated).toHaveBeenCalledTimes(1);
-
-    rerender(<OverlayScrollbarsComponent events={{ updated: onUpdated }} ref={ref} />);
-
-    ref.current!.instance()!.update(true);
-    expect(onUpdatedInitial).toHaveBeenCalledTimes(2);
-    expect(onUpdated).toHaveBeenCalledTimes(2);
+    // instance didn't change
+    expect(instance).toBe(ref.current!.instance());
 
     rerender(
-      <OverlayScrollbarsComponent events={{ updated: [onUpdated, onUpdatedInitial] }} ref={ref} />
+      <OverlayScrollbarsComponent
+        element="span"
+        events={{ updated: [onUpdated, onUpdatedInitial] }}
+        ref={ref as any as RefObject<OverlayScrollbarsComponentRef<'span'>>}
+      />
     );
 
-    ref.current!.instance()!.update(true);
+    const newElementInstance = ref.current!.instance()!;
+    expect(newElementInstance).not.toBe(instance);
     expect(onUpdatedInitial).toHaveBeenCalledTimes(3);
     expect(onUpdated).toHaveBeenCalledTimes(3);
 
-    // unregister works with `[]`, `null` or `undefined`
-    rerender(<OverlayScrollbarsComponent events={{ updated: null }} ref={ref} />);
+    // reset events with `undefined`, `null`, `false` or `{}`
+    rerender(
+      <OverlayScrollbarsComponent
+        element="span"
+        events={undefined}
+        ref={ref as any as RefObject<OverlayScrollbarsComponentRef<'span'>>}
+      />
+    );
 
-    ref.current!.instance()!.update(true);
+    newElementInstance.update(true);
+    expect(newElementInstance).toBe(ref.current!.instance());
     expect(onUpdatedInitial).toHaveBeenCalledTimes(3);
     expect(onUpdated).toHaveBeenCalledTimes(3);
   });