Merge pull request #189 from streamich/next

Next

.circleci/config.yml

@@ -55,6 +55,27 @@ jobs:
           path: ~/repo/storybook-static
       - *Commit_Status_Storybook
 
+  next:
+    <<: *container
+    steps:
+      - checkout
+      - *Versions
+      - *Install
+      - *Build
+      - *Build_Storybook
+      - *Test
+      - store_artifacts:
+          path: ~/repo/storybook-static
+      - *Commit_Status_Storybook
+      - run:
+          name: Setup GitHub
+          command: |
+            git config --global user.email "[email protected]"
+            git config --global user.name "streamich"
+            git remote rm origin
+            git remote add origin https://${GITHUB_TOKEN}@github.com/streamich/react-use
+      - *Release
+
   master:
     <<: *container
     steps:
@@ -87,7 +108,15 @@ workflows:
             branches:
               ignore:
                 - master
+                - next
                 - gh-pages
+  next:
+    jobs:
+      - next:
+          context: common-env-vars
+          filters:
+            branches:
+              only: next
   master:
     jobs:
       - master:

README.md

@@ -36,15 +36,15 @@
   - [`useGeolocation`](./docs/useGeolocation.md) — tracks geo location state of user's device. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usegeolocation--demo)
   - [`useHover` and `useHoverDirty`](./docs/useHover.md) — tracks mouse hover state of some element. [![][img-demo]](https://codesandbox.io/s/zpn583rvx)
   - [`useIdle`](./docs/useIdle.md) — tracks whether user is being inactive.
-  - [`useKeyPress`](./docs/useKeyPress.md) — tracks whether a keyboard key—or set of keys—was pressed.
-  - [`useKeyPressEvent`](./docs/useKeyPressEvent.md) — call `onKeyDown` and `onKeyUp` callbacks, when key pressed. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usekeypressevent--demo)
+  - [`useKey`](./docs/useKey.md), [`useKeyPress`](./docs/useKeyPress.md), [`useKeyboardJs`](./docs/useKeyPressEvent.md), and [`useKeyPressEvent`](./docs/useKeyPressEvent.md) — track keys. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usekeypressevent--demo)
   - [`useLocation`](./docs/useLocation.md) — tracks page navigation bar location state.
   - [`useMedia`](./docs/useMedia.md) — tracks state of a CSS media query. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usemedia--demo)
   - [`useMediaDevices`](./docs/useMediaDevices.md) — tracks state of connected hardware devices.
   - [`useMotion`](./docs/useMotion.md) — tracks state of device's motion sensor.
   - [`useMouse` and `useMouseHovered`](./docs/useMouse.md) — tracks state of mouse position. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usemouse--docs)
   - [`useNetwork`](./docs/useNetwork.md) — tracks state of user's internet connection.
   - [`useOrientation`](./docs/useOrientation.md) — tracks state of device's screen orientation.
+  - [`usePageLeave`](./docs/usePageLeave.md) — triggers when mouse leaves page boundaries.
   - [`useScroll`](./docs/useScroll.md) — tracks some HTML element's scroll position. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usescroll--docs)
   - [`useSize`](./docs/useSize.md) — tracks some HTML element's dimensions.
   - [`useWindowScroll`](./docs/useWindowScroll.md) — tracks `Window` scroll position. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usewindowscroll--docs)
@@ -55,6 +55,8 @@
   - [`useAudio`](./docs/useAudio.md) — plays audio and exposes its controls. [![][img-demo]](https://codesandbox.io/s/2o4lo6rqy)
   - [`useClickAway`](./docs/useClickAway.md) — triggers callback when user clicks outside target area.
   - [`useCss`](./docs/useCss.md) — dynamically adjusts CSS.
+  - [`useDrop` and `useDropArea`](./docs/useDrop.md) — tracks file, link and copy-paste drops.
+  - [`useFullscreen`](./docs/useFullscreen.md) — display an element or video full-screen. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/ui-usefullscreen--demo)
   - [`useSpeech`](./docs/useSpeech.md) — synthesizes speech from a text string. [![][img-demo]](https://codesandbox.io/s/n090mqz69m)
   - [`useVideo`](./docs/useVideo.md) — plays video, tracks its state, and exposes playback controls. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/ui-usevideo--demo)
   - [`useWait`](./docs/useWait.md) — complex waiting management for UIs.
@@ -76,11 +78,12 @@
   - [`useLocalStorage`](./docs/useLocalStorage.md) — manages a value in `localStorage`.
   - [`useLockBodyScroll`](./docs/useLockBodyScroll.md) — lock scrolling of the body element.
   - [`useSessionStorage`](./docs/useSessionStorage.md) — manages a value in `sessionStorage`.
-  - [`useThrottle`](./docs/useThrottle.md) — throttles a function. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/side-effects-usethrottle--demo)
+  - [`useThrottle` and `useThrottleFn`](./docs/useThrottle.md) — throttles a function. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/side-effects-usethrottle--demo)
   - [`useTitle`](./docs/useTitle.md) — sets title of the page.
     <br/>
     <br/>
 - [**Lifecycles**](./docs/Lifecycles.md)
+  - [`useEvent`](./docs/useEvent.md) &mdash; subscribe to events.
   - [`useLifecycles`](./docs/useLifecycles.md) &mdash; calls `mount` and `unmount` callbacks.
   - [`useRefMounted`](./docs/useRefMounted.md) &mdash; tracks if component is mounted.
   - [`usePromise`](./docs/usePromise.md) &mdash; resolves promise only while component is mounted.

docs/useDrop.md

@@ -0,0 +1,49 @@
+# `useDrop` and `useDropArea`
+
+Triggers on file, link drop and copy-paste.
+
+`useDrop` tracks events for the whole page, `useDropArea` tracks drop events
+for a specific element.
+
+
+## Usage
+
+`useDrop`:
+
+```jsx
+import {useDrop} from 'react-use';
+
+const Demo = () => {
+  const state = useDrop({
+    onFiles: files => console.log('files', files),
+    onUri: uri => console.log('uri', uri),
+    onText: text => console.log('text', text),
+  });
+
+  return (
+    <div>
+      Drop something on the page.
+    </div>
+  );
+};
+```
+
+`useDropArea`:
+
+```jsx
+import {useDropArea} from 'react-use';
+
+const Demo = () => {
+  const [bond, state] = useDropArea({
+    onFiles: files => console.log('files', files),
+    onUri: uri => console.log('uri', uri),
+    onText: text => console.log('text', text),
+  });
+
+  return (
+    <div {...bond}>
+      Drop something here.
+    </div>
+  );
+};
+```

docs/useEvent.md

@@ -0,0 +1,38 @@
+# `useEvent`
+
+React sensor hook that subscribes a `handler` to events.
+
+
+## Usage
+
+```jsx
+import useEvent from 'react-use/lib/useEvent';
+import useList from 'react-use/lib/useList';
+
+const Demo = () => {
+  const [list, {push}] = useList();
+  const onkeydown = ({key}) => {
+    push(key);
+  };
+  useEvent('keydown', useCallback(onkeydown, []));
+
+  return (
+    <div>
+      <p>
+        Press some keys on your keyboard.
+      </p>
+      <pre>
+        {JSON.stringify(list, null, 4)}
+      </pre>
+    </div>
+  );
+};
+```
+
+
+## Examples
+
+```js
+useEvent('keydown', handler)
+useEvent('scroll', handler, window, {capture: true})
+```

docs/useFullscreen.md

@@ -0,0 +1,30 @@
+# `useFullscreen`
+
+Display an element full-screen, optional fallback for fullscreen video on iOS.
+
+## Usage
+
+```jsx
+import useFullscreen from 'react-use/lib/useFullscreen';
+import useToggle from 'react-use/lib/useToggle';
+
+const Demo = () => {
+  const ref = useRef(null)
+  const [show, toggle] = useToggle(false);
+  const isFullscreen = useFullscreen(ref, show, {onClose: () => toggle(false)});
+
+  return (
+    <div ref={ref} style={{backgroundColor: 'white'}}>
+      <div>{isFullscreen ? 'Fullscreen' : 'Not fullscreen'}</div>
+      <button onClick={() => toggle()}>Toggle</button>
+      <video src="http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4" autoPlay />
+    </div>
+  );
+};
+```
+
+## Reference
+
+```ts
+useFullscreen(ref, show, {onClose})
+```

docs/useKey.md

@@ -0,0 +1,46 @@
+# `useKey`
+
+React UI sensor hook that executes a `handler` when a keyboard key is used.
+
+## Usage
+
+```jsx
+import useKey from 'react-use/lib/useKey';
+
+const Demo = () => {
+  const [count, set] = useState(0);
+  const increment = () => set(count => ++count);
+  useKey('ArrowUp', increment);
+
+  return (
+    <div>
+      Press arrow up: {count}
+    </div>
+  );
+};
+```
+
+Or as render-prop:
+
+```jsx
+import UseKey from 'react-use/lib/comps/UseKey';
+
+<UseKey filter='a' fn={() => alert('"a" key pressed!')} />
+```
+
+
+## Reference
+
+```js
+useKey(filter, handler, options?, deps?)
+```
+
+
+## Examples
+
+```js
+useKey('a', () => alert('"a" pressed'));
+
+const predicate = (event) => event.key === 'a'
+useKey(predicate, handler, {event: 'keyup'});
+```

docs/useKeyPress.md

@@ -3,60 +3,34 @@
 React UI sensor hook that detects when the user is pressing a specific
 key on their keyboard.
 
-Complex bindings like detecting when multiple keys are held down at the same
-time or requiring them to be held down in a specified order are also available
-via [KeyboardJS key combos](https://github.com/RobertWHurst/KeyboardJS).
-Check its documentation for further details on how to make combo strings.
-
-Requires `keyboardjs`:
-
-```bash
-npm add keyboardjs
-# or
-yarn add keyboardjs
-```
 
 ## Usage
 
 ```jsx
-import { useKeyPress } from "react-use";
+import useKeyPress from 'react-use/lib/useKeyPress';
+
+const keys = ['1', '2', '3', '4', '5', '6', '7', '8', '9', '0'];
 
 const Demo = () => {
-  const hasPressedQ = useKeyPress("q");
-  const hasPressedW = useKeyPress("w");
-  const hasPressedE = useKeyPress("e");
-  const hasPressedR = useKeyPress("r");
-  const hasPressedT = useKeyPress("t");
-  const hasPressedY = useKeyPress("y");
-  const hasPressedWord = useKeyPress("q + w + e + r + t + y", {
-    useKeyboardJS: true
-  });
+  const states = [];
+  for (const key of keys) states.push(useKeyPress(key));
 
   return (
-    <div>
-      Try pressing each one of these at a time: <code>Q W E R T Y</code>
-      {!hasPressedWord && (
-        <div>
-          {hasPressedQ && "Q"}
-          {hasPressedW && "W"}
-          {hasPressedE && "E"}
-          {hasPressedR && "R"}
-          {hasPressedT && "T"}
-          {hasPressedY && "Y"}
-        </div>
-      )}
-      <div>And now press them all at once!</div>
-      <div>{hasPressedWord && "Q + W + E + R + T + Y"}</div>
+    <div style={{textAlign: 'center'}}>
+      Try pressing numbers
+      <br />
+      {states.reduce((s, pressed, index) => s + (pressed ? (s ? ' + ' : '') + keys[index] : ''), '')}
     </div>
   );
 };
 ```
 
-## Reference
+
+## Examples
 
 ```js
-const hasPressedSingleKey = useKeyPress("<key>");
-const hasPressedKeyCombo = useKeyPress("<key combo>", {
-  useKeyboardJS: true
-});
+const isPressed = useKeyPress('a');
+
+const predicate = (event) => event.key === 'a';
+const isPressed = useKeyPress(predicate);
 ```

docs/useKeyPressEvent.md

@@ -1,32 +1,15 @@
 # `useKeyPressEvent`
 
-React UI sensor hook that detects when the user is pressing a specific
-key on their keyboard and fires a specified keyup and/or keydown effect. If
-you only need to retrieve the state, see [useKeyPress](useKeyPress.md).
-
-Complex bindings like detecting when multiple keys are held down at the same
-time or requiring them to be held down in a specified order are also available
-via [KeyboardJS key combos](https://github.com/RobertWHurst/KeyboardJS).
-Check its documentation for further details on how to make combo strings.
-
-The first argument is the key(s) to watch. If only a second argument
-(a function) is passed, it will be used in the keydown event. On the other hand,
-if a second and third argument are passed, the second will be used in the keyup
-event and the third in the keydown event. Essentially, keydown takes precedence.
-
-Requires `keyboardjs`:
-
-```bash
-npm add keyboardjs
-# or
-yarn add keyboardjs
-```
+This hook fires `keydown` and `keyup` calllbacks, similar to how [`useKey`](./useKey.md)
+hook does, but it only triggers each callback once per press cycle. For example,
+if you press and hold a key, it will fire `keydown` callback only once.
+
 
 ## Usage
 
 ```jsx
 import React, { useState } from React;
-import { useKeyPressEvent } from "react-use";
+import useKeyPressEvent from 'react-use/lib/useKeyPressEvent';
 
 const Demo = () => {
   const [count, setCount] = useState(0);
@@ -50,9 +33,11 @@ const Demo = () => {
 };
 ```
 
+
 ## Reference
 
 ```js
-useKeyPressEvent('<key>', onKeydown);
-useKeyPressEvent('<key>', onKeyup, onKeydown);
+useKeyPressEvent('<key>', keydown);
+useKeyPressEvent('<key>', keydown, keyup);
+useKeyPressEvent('<key>', keydown, keyup, useKeyPress);
 ```