docs: add ShouldUpdate docs

Author: streamich

README.md

@@ -36,15 +36,15 @@ const MyComponent = mock();
      - [`mock()`](./docs/en/mock.md) and [`loadable()`](./docs/en/loadable.md)
      - [`lazy()`](./docs/en/lazy.md), [`delayed()`](./docs/en/delayed.md), and [`viewport()`](./docs/en/viewport.md)
   - [Inversion](./docs/en/Inversion.md)
-     - [`invert()`](./docs/en/invert.md) and [`<Inverted>`](./docs/en/invert.md#inverted)
-        - `<ShouldUpdate>`
      - [`<State>`](./docs/en/State.md) and [`withState()`](./docs/en/State.md#withstate-hoc)
         - [`<Toggle>`](./docs/en/Toggle.md), [`withToggle()`](./docs/en/Toggle.md#withtoggle-hoc), and [`@withToggle`](./docs/en/Toggle.md#withtoggle-decorator)
         - [`<Flipflop>`](./docs/en/Flipflop.md), [`withFlipflop()`](./docs/en/Flipflop.md#withflipflop-hoc), and [`@withFlipflop`](./docs/en/Flipflop.md#withflipflop-decorator)
         - [`<Value>`](./docs/en/Value.md), [`withValue()`](./docs/en/Value.md#withvalue-hoc), and [`@withValue`](./docs/en/Value.md#withvalue-decorator)
         - [`<Counter>`](./docs/en/Counter.md), [`withCounter()`](./docs/en/Counter.md#withcounter-hoc) and [`@withCounter`](./docs/en/Counter.md#withcounter-decorator)
         - [`<List>`](./docs/en/List.md), [`withList()`](./docs/en/List.md#withlist-hoc), and [`@withList`](./docs/en/List.md#withlist-decorator)
         - [`<Map>`](./docs/en/Map.md), [`withMap()`](./docs/en/Map.md#withmap-hoc), and [`@withMap`](./docs/en/Map.md#withmap-decorator)
+     - [`<ShouldUpdate>`](./docs/en/ShouldUpdate.md), [`shouldUpdate()`](./docs/en/ShouldUpdate.md#shouldupdate-hoc), and [`pure()`](./docs/en/pure.md)
+     - [`invert()`](./docs/en/invert.md) and [`<Inverted>`](./docs/en/invert.md#inverted)
   - [Sensors](./docs/en/Sensors.md)
      - [`<ActiveSensor>`](./docs/en/ActiveSensor.md), [`withActive()`](./docs/en/ActiveSensor.md#withactive-hoc), and [`@withActive`](./docs/en/ActiveSensor.md#withactive-decorator)
      - [`<BatterySensor>`](./docs/en/BatterySensor.md), [`withBattery()`](./docs/en/BatterySensor.md#withbattery), and [`@withBattery`](./docs/en/BatterySensor.md#withbattery-1)

docs/en/README.md

@@ -5,14 +5,15 @@
      - [`mock()`](./mock.md) and [`loadable()`](./loadable.md)
      - [`lazy()`](./lazy.md), [`delayed()`](./delayed.md), and [`viewport()`](./viewport.md)
   - [Inversion](./Inversion.md)
+    - [`<State>`](./State.md) and [`withState()`](./State.md#withstate-hoc)
+      - [`<Toggle>`](./Toggle.md), [`withToggle()`](./Toggle.md#withtoggle-hoc), and [`@withToggle`](./Toggle.md#withtoggle-decorator)
+      - [`<Flipflop>`](./Flipflop.md), [`withFlipflop()`](./Flipflop.md#withflipflop-hoc), and [`@withFlipflop`](./Flipflop.md#withflipflop-decorator)
+      - [`<Value>`](./Value.md), [`withValue()`](./Value.md#withvalue-hoc), and [`@withValue`](./Value.md#withvalue-decorator)
+      - [`<Counter>`](./Counter.md), [`withCounter()`](./Counter.md#withcounter-hoc) and [`@withCounter`](./Counter.md#withcounter-decorator)
+      - [`<List>`](./List.md), [`withList()`](./List.md#withlist-hoc), and [`@withList`](./List.md#withlist-decorator)
+      - [`<Map>`](./Map.md), [`withMap()`](./Map.md#withmap-hoc), and [`@withMap`](./Map.md#withmap-decorator)
+     - [`<ShouldUpdate>`](./ShouldUpdate.md), [`shouldUpdate()`](./ShouldUpdate.md#shouldupdate-hoc), and [`pure()`](./pure.md)
      - [`invert()`](./invert.md) and [`<Inverted>`](./invert.md#inverted)
-     - [`<State>`](./State.md) and [`withState()`](./State.md#withstate-hoc)
-        - [`<Toggle>`](./Toggle.md), [`withToggle()`](./Toggle.md#withtoggle-hoc), and [`@withToggle`](./Toggle.md#withtoggle-decorator)
-        - [`<Flipflop>`](./Flipflop.md), [`withFlipflop()`](./Flipflop.md#withflipflop-hoc), and [`@withFlipflop`](./Flipflop.md#withflipflop-decorator)
-        - [`<Value>`](./Value.md), [`withValue()`](./Value.md#withvalue-hoc), and [`@withValue`](./Value.md#withvalue-decorator)
-        - [`<Counter>`](./Counter.md), [`withCounter()`](./Counter.md#withcounter-hoc) and [`@withCounter`](./Counter.md#withcounter-decorator)
-        - [`<List>`](./List.md), [`withList()`](./List.md#withlist-hoc), and [`@withList`](./List.md#withlist-decorator)
-        - [`<Map>`](./Map.md), [`withMap()`](./Map.md#withmap-hoc), and [`@withMap`](./Map.md#withmap-decorator)
   - [Sensors](./Sensors.md)
      - [`<ActiveSensor>`](./ActiveSensor.md), [`withActive()`](./ActiveSensor.md#withactive-hoc), and [`@withActive`](./ActiveSensor.md#withactive-decorator)
      - [`<BatterySensor>`](./BatterySensor.md), [`withBattery()`](./BatterySensor.md#withbattery), and [`@withBattery`](./BatterySensor.md#withbattery-1)

docs/en/ShouldUpdate.md

@@ -0,0 +1,40 @@
+# `<ShouldUpdate>`
+
+Inverts `.shouldComponentUpdate()` life-cycle method. Allows you to use specify whether its children should update based
+on passed in props.
+
+
+## Usage
+
+The below example will always re-render on new `data`, because `when` method always returns `true`.
+
+```jsx
+import {ShouldUpdate} from 'libreact/lib/ShouldUpdate';
+
+<ShouldUpdate when={(newProps, oldProps) => true} props={data}>{(props) =>
+  <div>Hello world!</div>
+}</ShouldUpdate>
+```
+
+
+## Props
+
+  - `when` &mdash; required, function, return boolean whether its children should re-render. Receives new and old props as two arguments.
+  - `props` &mdash; required, object, props to pass to children.
+
+
+## `shouldUpdate()` HOC
+
+Higher order component that re-renders only when a condition is met.
+
+```jsx
+import {shouldUpdate} from 'libreact/lib/ShouldUpdate';
+
+const PrintOver3 = shouldUpdate((props) => props.cnt > 3)(Print);
+```
+
+The above example creates a `PrintOver3` component that will re-render only when
+`cnt` prop is greater than 3.
+
+
+See also [`pure()`](./pure.md).