From 1e74bdcf489ea659de89adc23f9a63c112714860 Mon Sep 17 00:00:00 2001
From: streamich <streamich@gmail.com>
Date: Sun, 12 Jan 2020 18:21:43 +0100
Subject: [PATCH] =?UTF-8?q?docs:=20=E2=9C=8F=EF=B8=8F=20add=20useScratch?=
 =?UTF-8?q?=20to=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                    |  1 +
 docs/useScratch.md           | 75 ++++++++++++++++++++++++++++++++++++
 stories/useScratch.story.tsx |  2 +-
 3 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 docs/useScratch.md

diff --git a/README.md b/README.md
index 3f9d1250..32cab21e 100644
--- a/README.md
+++ b/README.md
@@ -60,6 +60,7 @@
   - [`useNetwork`](./docs/useNetwork.md) &mdash; tracks state of user's internet connection.
   - [`useOrientation`](./docs/useOrientation.md) &mdash; tracks state of device's screen orientation.
   - [`usePageLeave`](./docs/usePageLeave.md) &mdash; triggers when mouse leaves page boundaries.
+  - [`useScratch`](./docs/useScratch.md) &mdash; tracks mouse click-and-scrub state.
   - [`useScroll`](./docs/useScroll.md) &mdash; tracks an HTML element's scroll position. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usescroll--docs)
   - [`useScrolling`](./docs/useScrolling.md) &mdash; tracks whether HTML element is scrolling.
   - [`useSize`](./docs/useSize.md) &mdash; tracks an HTML element's size.
diff --git a/docs/useScratch.md b/docs/useScratch.md
new file mode 100644
index 00000000..0ba6c311
--- /dev/null
+++ b/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;
+}
+```
diff --git a/stories/useScratch.story.tsx b/stories/useScratch.story.tsx
index 49fe1edb..43e9e31b 100644
--- a/stories/useScratch.story.tsx
+++ b/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 />);