docs: ✏️ add useScratch to docs

README.md

@@ -60,6 +60,7 @@
   - [`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.
+  - [`useScratch`](./docs/useScratch.md) — tracks mouse click-and-scrub state.
   - [`useScroll`](./docs/useScroll.md) — tracks an HTML element's scroll position. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usescroll--docs)
   - [`useScrolling`](./docs/useScrolling.md) — tracks whether HTML element is scrolling.
   - [`useSize`](./docs/useSize.md) — tracks an HTML element's size.

docs/useScratch.md

@@ -0,0 +1,75 @@
+# `useScratch`
+
+React sensor hook that tracks state of mouse "scrubs" (or "scratches").
+
+## Usage
+
+```jsx
+import useScratch from 'react-use/lib/useScratch';
+
+const Demo = () => {
+  const [ref, state] = useScratch();
+
+  const blockStyle: React.CSSProperties = {
+    position: 'relative',
+    width: 400,
+    height: 400,
+    border: '1px solid tomato',
+  };
+
+  const preStyle: React.CSSProperties = {
+    pointerEvents: 'none',
+    userSelect: 'none',
+  };
+
+  let { x = 0, y = 0, dx = 0, dy = 0 } = state;
+  if (dx < 0) [x, dx] = [x + dx, -dx];
+  if (dy < 0) [y, dy] = [y + dy, -dy];
+
+  const rectangleStyle: React.CSSProperties = {
+    position: 'absolute',
+    left: x,
+    top: y,
+    width: dx,
+    height: dy,
+    border: '1px solid tomato',
+    pointerEvents: 'none',
+    userSelect: 'none',
+  };
+
+  return (
+    <div ref={ref} style={blockStyle}>
+      <pre style={preStyle}>{JSON.stringify(state, null, 4)}</pre>
+      {state.isScratching && <div style={rectangleStyle} />}
+    </div>
+  );
+};
+```
+
+## Reference
+
+```ts
+const [ref, state] = useScratch();
+```
+
+`state` is:
+
+```ts
+export interface ScratchSensorState {
+  isScratching: boolean;
+  start?: number;
+  end?: number;
+  x?: number;
+  y?: number;
+  dx?: number;
+  dy?: number;
+  docX?: number;
+  docY?: number;
+  posX?: number;
+  posY?: number;
+  elH?: number;
+  elW?: number;
+  elX?: number;
+  elY?: number;
+}
+```

stories/useScratch.story.tsx

@@ -42,5 +42,5 @@ const Demo = () => {
 };
 
 storiesOf('Sensors/useScratch', module)
-  // .add('Docs', () => <ShowDocs md={require('../docs/useScroll.md')} />)
+  .add('Docs', () => <ShowDocs md={require('../docs/useScratch.md')} />)
   .add('Demo', () => <Demo />);