feat(recipes): new recipes section with custom Readme files

Author: Rendez

README.md

@@ -26,7 +26,7 @@ ReactIntersectionObserver is good at:
   + [No bookkeeping](#no-bookkeeping)
   + [No extra markup](#no-extra-markup)
   + [Easy to adopt](#easy-to-adopt)
-* [Demo](#demo)
+* [Examples](#examples)
 * [Options](#options)
 * [Notes](#notes)
 * [Polyfill](#polyfill)
@@ -122,12 +122,20 @@ Some of the things you may want to use ReactIntersectionObserver for:
 * Occlusion culling - Don't render an object until is close to the viewport edges
 * Sentinel Scrolling - Infinite scroller with a recycled Sentinel
 
-## Demo
+## Examples
 
-Find multiple examples and usage guidelines in: [https://researchgate.github.io/react-intersection-observer/](https://researchgate.github.io/react-intersection-observer/)
+### Demos
+
+Find multiple examples and usage guidelines under: [https://researchgate.github.io/react-intersection-observer/](https://researchgate.github.io/react-intersection-observer/)
 
 [![demo](https://github.com/researchgate/react-intersection-observer/blob/master/.github/demo.gif?raw=true)](https://researchgate.github.io/react-intersection-observer/)
 
+### Recipes
+
+Recipes are useful code snippets solutions to common problems, for example, how to use ReactIntersectionObserver within a [Higher Order Component](https://researchgate.github.io/react-intersection-observer/?selectedKind=Recipes&selectedStory=Higher%20Order%20Component).
+
+Discover more recipes in our [examples section](examples/README.md).
+
 ## Options
 
 ### root

examples/README.md

@@ -0,0 +1,37 @@
+## Examples
+
+Welcome to the code examples section!
+
+Here you'll find usage examples and recipes. For a full list of examples, take a look in our [storybook page](https://researchgate.github.io/react-intersection-observer/?selectedKind=Examples).
+
+* [Basic usage on Window](https://researchgate.github.io/react-intersection-observer/?selectedKind=Examples&selectedStory=Window)
+* [Usage within a scroller/frame](https://researchgate.github.io/react-intersection-observer/?selectedKind=Examples&selectedStory=Frame)
+* [Using thresholds](https://researchgate.github.io/react-intersection-observer/?selectedKind=Examples&selectedStory=Thresholds)
+* [Using the rootMargin option](https://researchgate.github.io/react-intersection-observer/?selectedKind=Examples&selectedStory=Margin)
+* [Using the onlyOnce option](https://researchgate.github.io/react-intersection-observer/?selectedKind=Examples&selectedStory=Once)
+
+## Recipes
+
+Here you [will find useful code snippets](https://researchgate.github.io/react-intersection-observer/?selectedKind=Recipes) to common situations that can be approached with ReactIntersectionObserver:
+
+* [Higher Order Component](https://researchgate.github.io/react-intersection-observer/?selectedKind=Recipes&selectedStory=Higher%20Order%20Component)
+* [Tracking Ad Impressions](https://researchgate.github.io/react-intersection-observer/?selectedKind=Recipes&selectedStory=Ad%20Impressions)
+
+### Can I submit a new recipe?
+
+Yes, of course!
+
+1. Fork the code repo.
+2. Create your new recipe in the correct subfolder within `./examples/components/` (create a new folder if it doesn't already exist).
+3. Make sure you have included a README as well as your source file.
+4. Submit a PR.
+
+_If you haven't yet, please read our [contribution guidelines](https://github.com/researchgate/react-intersection-observer/blob/master/.github/CONTRIBUTING.md)._
+
+### What license are the recipes released under?
+
+By default, all newly submitted code is licensed under the MIT license.
+
+### How else can I contribute?
+
+Recipes don't always have to be code - great documentation, tutorials, general tips and even general improvements to our examples folder are greatly appreciated.

examples/components/HigherOrderComponent/README.md

@@ -1,5 +1,9 @@
 ## Higher order component
 
+A common way to avoid repetiton and dynamic option setting is to use _HOC_. Since our component reuses instances based on **all** the options, you don't have to worry about bookkeeping of instances. Create as many HOC as you need; they can be as flexible as you need them to be.
+
+The next example illustrates in a simple way how a _HOC_ is used to wrap target elements for occlusion culling:
+
 ### withIntersectionObserver.js
 ```jsx
 import React, { Component } from 'react';

examples/components/OnlyOnce/README.md

@@ -1,4 +1,4 @@
-Basic usage of **IntersectionObserver** with **onlyOnce** that will only trigger an event once as soon as **isIntersecting** is true:
+The option `onlyOnce` applied to the component will only trigger an event once, when the target detects `isIntersecting` is truthy. This is specially useful when you need a disposable observer, and you want to prevent re-rendering the element after that:
 
 ```jsx
 import React, { Component } from 'react';

examples/components/WindowFrame/README.md

@@ -1,3 +1,3 @@
-Usage within a scrollable frame that changes the className of the observed **<div />** element when the visibility changes.
-    
-For more see the **<Window />** example.
+Usage within a scrollable frame or even iframes should behave as expected. Note that in the example we're using Window as the root, which indicates the observed target triggers changes when intersecting with the viewport, in this case Window.
+
+However, we can always use a different root. Check out the [rootMargin example](https://researchgate.github.io/react-intersection-observer/?selectedKind=Examples&selectedStory=Margin), where we use a different approach to set the `root` option.

examples/components/WithRootMargin/README.md

@@ -1,4 +1,6 @@
-Usage of **IntersectionObserver** with negative bottom rootMargin:
+The option `rootMargin`'s syntax follows that of the `margin` CSS property. The unit(s) however **must** be provided in either `px` or `%` or both. It can also contain _negative values_, which are very useful to shrink the viewport size. Interestingly a percentage value works great to determine if an item is visible on very different screen sizes, e.g.: mobile vs desktop screens.
+
+Note that in the example below, we conciously show how to set a root to DOM reference using the `disable` option. This option accepts types `Element` and `String`. A more effective way is then to pass a valid `querySelector` string instead.
 
 ```jsx
 import React, { Component } from 'react';

examples/components/WithThresholds/README.md

@@ -1,4 +1,9 @@
-Usage of **IntersectionObserver** with tresholds, triggering an event for each defined points in the array:
+The option `threshold` is either a single number or an array of numbers which indicate at what percentage of the target's visibility the observer's callback should be executed. If you only want to detect when visibility passes the 50% mark, you can use a value of 0.5. If you want the callback run every time visibility passes another 25%, you would specify the array [0, 0.25, 0.5, 0.75, 1].
+
+The default is 0 (meaning as soon as even one pixel is visible, the callback will be run).
+A value of 1.0 means that the threshold isn't considered passed until every pixel is visible.
+
+Note that when comparing old and new props, our component compares the value of the `treshold` array for convenience, so you don't have to necessarily keep a reference to it. This is specially useful when using within a functional component.
 
 ```jsx
 import React, { Component } from 'react';