cozy-ui 83.2.0 → 83.3.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+# [83.3.0](https://github.com/cozy/cozy-ui/compare/v83.2.0...v83.3.0) (2023-04-21)
+
+
+### Features
+
+* Add event listener on ref ([5fcc981](https://github.com/cozy/cozy-ui/commit/5fcc981))
+* Add ExtendableFab ([511b5fc](https://github.com/cozy/cozy-ui/commit/511b5fc))
+* Add useScroll hook to get scroll position from an element ([fdf2a74](https://github.com/cozy/cozy-ui/commit/fdf2a74))
+
 # [83.2.0](https://github.com/cozy/cozy-ui/compare/v83.1.1...v83.2.0) (2023-04-21)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozy-ui",
-  "version": "83.2.0",
+  "version": "83.3.0",
   "description": "Cozy apps UI SDK",
   "main": "./index.js",
   "bin": {

package/react/Fab/ExtendableFab.jsx

@@ -0,0 +1,30 @@
+import React from 'react'
+
+import Icon from '../Icon'
+import useScroll from '../hooks/useScroll'
+import Fab from '.'
+
+const ExtendableFab = ({
+  label,
+  icon,
+  follow,
+  topLimit = 50,
+  scrollOptions,
+  ...rest
+}) => {
+  const { scrollTop } = useScroll(follow, scrollOptions)
+  const isBelowTopLimit = scrollTop < topLimit
+
+  return (
+    <Fab
+      aria-label={label}
+      variant={isBelowTopLimit ? 'extended' : 'circular'}
+      {...rest}
+    >
+      <Icon icon={icon} {...(isBelowTopLimit && { className: 'u-mr-half' })} />
+      {isBelowTopLimit && label}
+    </Fab>
+  )
+}
+
+export default ExtendableFab

package/react/Fab/Readme.md

@@ -77,3 +77,41 @@ const props = [{ color: 'primary' }, { color: 'secondary' }, { color: 'inherit',
   )}
 </Grid>
 ```
+
+### ExtendableFab
+
+To increase discoverability, the FAB can be extended at first and then changed to standard when scrolling. The ExtendableFab will only revert to extended when the user has returned on to the top of the page.
+
+```jsx
+import { ExtendableFab } from 'cozy-ui/transpiled/react/Fab'
+import PlusIcon from 'cozy-ui/transpiled/react/Icons/Plus'
+import DemoProvider from 'cozy-ui/docs/components/DemoProvider'
+import {useRef} from 'react'
+
+const Demo = ({ onClick, className }) => {
+  const box = useRef(null)
+
+  return (
+    <div className="u-h-4 u-ov-scroll" style={{border: '2px dotted red'}} ref={box}>
+      <ExtendableFab
+        label="Add"
+        follow={box}
+        color="primary"
+        className="u-mb-1"
+        icon={PlusIcon}
+        style={{position: 'sticky', top: 16, left: 16}}
+      />
+      <div className="u-p-1">Scroll Horizontally</div>
+      <div className="u-h-8"></div>
+    </div>
+  )
+};
+
+<DemoProvider>
+  <Demo />
+</DemoProvider>
+```
+
+**Note:**
+
+The element to follow for scrolling changes according to the screen size in general in Cozy applications. On mobile, the window should be targeted otherwhise it depends on the dom element that has a scroll overflow.

package/react/Fab/index.js

@@ -1,3 +1,4 @@
 import Fab from '@material-ui/core/Fab'
 
 export default Fab
+export { default as ExtendableFab } from './ExtendableFab'

package/react/helpers/ref.js

@@ -0,0 +1,11 @@
+export function isRef(obj) {
+  return (
+    obj !== null &&
+    typeof obj === 'object' &&
+    Object.prototype.hasOwnProperty.call(obj, 'current')
+  )
+}
+
+export function unRef(element) {
+  return isRef(element) ? element.current : element
+}

package/react/helpers/ref.spec.js

@@ -0,0 +1,28 @@
+import { isRef, unRef } from './ref'
+
+describe('isRef', () => {
+  it('should return false when element is null', () => {
+    expect(isRef(null)).toBe(false)
+  })
+  it('should return false when element is an object without current', () => {
+    expect(isRef({ something: true })).toBe(false)
+  })
+  it('should return true when element is an object with current', () => {
+    expect(isRef({ current: 'test' })).toBe(true)
+  })
+})
+
+describe('unRef', () => {
+  it('should return the current property when it is a ref', () => {
+    const ref = { current: 'test' }
+    expect(unRef(ref)).toBe('test')
+  })
+  it('should return the element when it is only a string', () => {
+    const string = 'test'
+    expect(unRef(string)).toBe(string)
+  })
+  it('should return the element when it is only a object', () => {
+    const obj = { something: true }
+    expect(unRef(obj)).toBe(obj)
+  })
+})

package/react/hooks/useEventListener.js

@@ -1,12 +1,14 @@
 import { useEffect } from 'react'
+import { unRef } from '../helpers/ref'
 
 const useEventListener = (element, event, cb) => {
   useEffect(() => {
-    if (element && event && cb) {
-      element.addEventListener(event, cb)
+    const currentElement = unRef(element)
+    if (currentElement && event && cb) {
+      currentElement.addEventListener(event, cb)
 
       return () => {
-        element.removeEventListener(event, cb)
+        currentElement.removeEventListener(event, cb)
       }
     }
   }, [event, cb, element])

package/react/hooks/useEventListener.spec.js

@@ -22,6 +22,23 @@ describe('useEventListener', () => {
     expect(cb).toHaveBeenCalledTimes(1)
   })
 
+  it('should subscribe to the given event on the given ref', async () => {
+    const cb = jest.fn()
+    const ref = {
+      current: document
+    }
+
+    const { unmount } = renderHook(() => useEventListener(ref, 'click', cb))
+
+    triggerEvent(document, 'click')
+    expect(cb).toHaveBeenCalledTimes(1)
+
+    unmount()
+
+    triggerEvent(document, 'click')
+    expect(cb).toHaveBeenCalledTimes(1)
+  })
+
   it('should not subscribe for an undefined element', async () => {
     const cb = jest.fn()
     const { result } = renderHook(() =>
@@ -30,6 +47,15 @@ describe('useEventListener', () => {
     expect(result.error).not.toBeDefined()
   })
 
+  it('should not subscribe for an undefined ref element', async () => {
+    const cb = jest.fn()
+    const ref = {
+      current: undefined
+    }
+    const { result } = renderHook(() => useEventListener(ref, 'click', cb))
+    expect(result.error).not.toBeDefined()
+  })
+
   it('should not subscribe for an undefined event', async () => {
     const cb = jest.fn()
     const { result } = renderHook(() => useEventListener(window, undefined, cb))

package/react/hooks/useScroll.jsx

@@ -0,0 +1,44 @@
+import { useState } from 'react'
+import debounce from 'lodash/debounce'
+
+import useEventListener from './useEventListener'
+import { unRef } from '../helpers/ref'
+
+/**
+ * Get scrollTop & scrollLeft from scroll event
+ * @param {HTMLElement|React.RefObject} element - Element or Ref to listen scroll event
+ * @param {Object} options
+ * @param {number} options.delay - Delay in ms before calling the callback
+ * @returns {{ scrollTop: number, scrollLeft: number}} - Scroll state
+ */
+const useScroll = (element, { delay = 250 } = {}) => {
+  const [scroll, setScroll] = useState({
+    scrollTop: 0,
+    scrollLeft: 0
+  })
+
+  const handleScroll = debounce(() => {
+    const mainElement = unRef(element)
+
+    if (mainElement === window) {
+      setScroll({
+        scrollTop: window.scrollY,
+        scrollLeft: window.scrollX
+      })
+    } else {
+      setScroll({
+        scrollTop: mainElement.scrollTop,
+        scrollLeft: mainElement.scrollLeft
+      })
+    }
+  }, delay)
+
+  // For Desktop
+  useEventListener(element, 'scroll', handleScroll)
+  // For Mobile
+  useEventListener(element, 'touchmove', handleScroll)
+
+  return scroll
+}
+
+export default useScroll

package/react/hooks/useScroll.md

@@ -0,0 +1,34 @@
+React hook that get scrollTop and direction properties when the scroll position of a react ref or a dom node changes.
+
+**A focus on performance**
+
+Scroll events can be issued at a high frequency. To avoid massive re-rendering, the callback is only fire every 250ms by default. You can reduce this delay using the options, as in the example below.
+
+```jsx
+import useScroll from 'cozy-ui/transpiled/react/hooks/useScroll'
+import Fab from 'cozy-ui/transpiled/react/Fab'
+import Icon from 'cozy-ui/transpiled/react/Icon'
+import PlusIcon from 'cozy-ui/transpiled/react/Icons/Plus'
+import DemoProvider from 'cozy-ui/docs/components/DemoProvider'
+import {useRef, useEffect} from 'react'
+
+const Demo = ({ onClick, className }) => {
+  const box = useRef(null)
+  const { scrollTop, scrollLeft } = useScroll(box, { delay: 50 })
+
+  return (
+    <div className="u-ta-center">
+      <div className="u-pb-1">Vertically scrolled of {scrollTop}px</div>
+      <div className="u-pb-1">Horizontally scrolled of {scrollLeft}px</div>
+      <div className="u-h-4 u-ov-scroll" style={{ border: '2px dotted red'}} ref={box}>
+        <div className="u-p-1"> Scroll Vertically and Horizontally</div>
+        <div className="u-h-8" style={{ width: '150vw'}}></div>
+      </div>
+    </div>
+  )
+};
+
+<DemoProvider>
+  <Demo />
+</DemoProvider>
+```

package/react/hooks/useScroll.spec.jsx

@@ -0,0 +1,56 @@
+import { renderHook, act } from '@testing-library/react-hooks'
+import useScroll from './useScroll'
+
+jest.mock('lodash/debounce', () => fn => fn)
+
+describe('useScroll', () => {
+  describe('horizontal scrolling', () => {
+    it('should detect from an element', () => {
+      const mockElement = document.createElement('div')
+
+      const { result } = renderHook(() => useScroll(mockElement))
+
+      act(() => {
+        mockElement.scrollTop = 50
+        mockElement.dispatchEvent(new CustomEvent('scroll'))
+      })
+
+      expect(result.current.scrollTop).toBe(50)
+    })
+    it('should detect from a window', () => {
+      const { result } = renderHook(() => useScroll(window))
+
+      act(() => {
+        window.scrollY = 50
+        window.dispatchEvent(new CustomEvent('scroll'))
+      })
+
+      expect(result.current.scrollTop).toBe(50)
+    })
+  })
+
+  describe('vertical scrolling', () => {
+    it('should detect from an element', () => {
+      const mockElement = document.createElement('div')
+
+      const { result } = renderHook(() => useScroll(mockElement))
+
+      act(() => {
+        mockElement.scrollLeft = 50
+        mockElement.dispatchEvent(new CustomEvent('scroll'))
+      })
+
+      expect(result.current.scrollLeft).toBe(50)
+    })
+    it('should detect from a window', () => {
+      const { result } = renderHook(() => useScroll(window))
+
+      act(() => {
+        window.scrollX = 50
+        window.dispatchEvent(new CustomEvent('scroll'))
+      })
+
+      expect(result.current.scrollLeft).toBe(50)
+    })
+  })
+})

package/react/index.js

@@ -97,7 +97,7 @@ export { default as UploadQueue } from './UploadQueue'
 export { default as CozyTheme } from './CozyTheme'
 export { default as Paper } from './Paper'
 export { default as ProgressionBanner } from './ProgressionBanner'
-export { default as Fab } from './Fab'
+export { default as Fab, ExtendableFab } from './Fab'
 export { default as SquareAppIcon } from './SquareAppIcon'
 export { default as FileImageLoader } from './FileImageLoader'
 export { default as Radios } from './Radios'

package/transpiled/react/Fab/ExtendableFab.js

@@ -0,0 +1,32 @@
+import _extends from "@babel/runtime/helpers/extends";
+import _objectWithoutProperties from "@babel/runtime/helpers/objectWithoutProperties";
+var _excluded = ["label", "icon", "follow", "topLimit", "scrollOptions"];
+import React from 'react';
+import Icon from "cozy-ui/transpiled/react/Icon";
+import useScroll from "cozy-ui/transpiled/react/hooks/useScroll";
+import Fab from "cozy-ui/transpiled/react/Fab";
+
+var ExtendableFab = function ExtendableFab(_ref) {
+  var label = _ref.label,
+      icon = _ref.icon,
+      follow = _ref.follow,
+      _ref$topLimit = _ref.topLimit,
+      topLimit = _ref$topLimit === void 0 ? 50 : _ref$topLimit,
+      scrollOptions = _ref.scrollOptions,
+      rest = _objectWithoutProperties(_ref, _excluded);
+
+  var _useScroll = useScroll(follow, scrollOptions),
+      scrollTop = _useScroll.scrollTop;
+
+  var isBelowTopLimit = scrollTop < topLimit;
+  return /*#__PURE__*/React.createElement(Fab, _extends({
+    "aria-label": label,
+    variant: isBelowTopLimit ? 'extended' : 'circular'
+  }, rest), /*#__PURE__*/React.createElement(Icon, _extends({
+    icon: icon
+  }, isBelowTopLimit && {
+    className: 'u-mr-half'
+  })), isBelowTopLimit && label);
+};
+
+export default ExtendableFab;

package/transpiled/react/Fab/index.js

@@ -1,2 +1,3 @@
 import Fab from '@material-ui/core/Fab';
-export default Fab;
+export default Fab;
+export { default as ExtendableFab } from './ExtendableFab';

package/transpiled/react/helpers/ref.js

@@ -0,0 +1,6 @@
+export function isRef(obj) {
+  return obj !== null && typeof obj === 'object' && Object.prototype.hasOwnProperty.call(obj, 'current');
+}
+export function unRef(element) {
+  return isRef(element) ? element.current : element;
+}

package/transpiled/react/hooks/useEventListener.js

@@ -1,11 +1,14 @@
 import { useEffect } from 'react';
+import { unRef } from "cozy-ui/transpiled/react/helpers/ref";
 
 var useEventListener = function useEventListener(element, event, cb) {
   useEffect(function () {
-    if (element && event && cb) {
-      element.addEventListener(event, cb);
+    var currentElement = unRef(element);
+
+    if (currentElement && event && cb) {
+      currentElement.addEventListener(event, cb);
       return function () {
-        element.removeEventListener(event, cb);
+        currentElement.removeEventListener(event, cb);
       };
     }
   }, [event, cb, element]);

package/transpiled/react/hooks/useScroll.js

@@ -0,0 +1,49 @@
+import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
+import { useState } from 'react';
+import debounce from 'lodash/debounce';
+import useEventListener from "cozy-ui/transpiled/react/hooks/useEventListener";
+import { unRef } from "cozy-ui/transpiled/react/helpers/ref";
+/**
+ * Get scrollTop & scrollLeft from scroll event
+ * @param {HTMLElement|React.RefObject} element - Element or Ref to listen scroll event
+ * @param {Object} options
+ * @param {number} options.delay - Delay in ms before calling the callback
+ * @returns {{ scrollTop: number, scrollLeft: number}} - Scroll state
+ */
+
+var useScroll = function useScroll(element) {
+  var _ref = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {},
+      _ref$delay = _ref.delay,
+      delay = _ref$delay === void 0 ? 250 : _ref$delay;
+
+  var _useState = useState({
+    scrollTop: 0,
+    scrollLeft: 0
+  }),
+      _useState2 = _slicedToArray(_useState, 2),
+      scroll = _useState2[0],
+      setScroll = _useState2[1];
+
+  var handleScroll = debounce(function () {
+    var mainElement = unRef(element);
+
+    if (mainElement === window) {
+      setScroll({
+        scrollTop: window.scrollY,
+        scrollLeft: window.scrollX
+      });
+    } else {
+      setScroll({
+        scrollTop: mainElement.scrollTop,
+        scrollLeft: mainElement.scrollLeft
+      });
+    }
+  }, delay); // For Desktop
+
+  useEventListener(element, 'scroll', handleScroll); // For Mobile
+
+  useEventListener(element, 'touchmove', handleScroll);
+  return scroll;
+};
+
+export default useScroll;

package/transpiled/react/index.js

@@ -75,7 +75,7 @@ export { default as UploadQueue } from './UploadQueue';
 export { default as CozyTheme } from './CozyTheme';
 export { default as Paper } from './Paper';
 export { default as ProgressionBanner } from './ProgressionBanner';
-export { default as Fab } from './Fab';
+export { default as Fab, ExtendableFab } from './Fab';
 export { default as SquareAppIcon } from './SquareAppIcon';
 export { default as FileImageLoader } from './FileImageLoader';
 export { default as Radios } from './Radios';