Merge pull request #9 from MailOnline/feat/various-2

Feat/various 2

Author: streamich

README.md

@@ -7,14 +7,14 @@
 React standard library, must-have toolbox for any React project.
 
   - Collection of React sensors, FaCCs, HOCs, context providers, dummies, and [other goodies](#contents).
-  - Isomorphic - all components work in browser and Node.js (and some in `react-native`).
-  - [See demos and docs](https://mailonline.github.io/libreact/).
+  - Isomorphic - all components work in browser and on server (and some in `react-native`).
+  - See [demos](https://mailonline.github.io/libreact/) and [docs](#contents).
 
 ## Installation
 
-```shell
-npm install libreact --save
-```
+<pre>
+npm i <a href="https://www.npmjs.com/package/libreact">libreact</a> --save
+</pre>
 
 ## Usage
 
@@ -35,32 +35,31 @@ const MyComponent = mock();
      - [`delayed()`](./docs/delayed.md)
      - [`invert()`](./docs/invert.md)
   - Sensors
-     - [`<BatterySensor>`](./docs/BatterySensor.md)
-     - [`<MediaDeviceSensor>`](./docs/MediaDeviceSensor.md)
-     - [`<MediaSensor>`](./docs/MediaSensor.md)
+     - [`<BatterySensor>`](./docs/BatterySensor.md), [`withBattery()`](./docs/BatterySensor.md#withbattery), and [`@withBattery`](./docs/BatterySensor.md#withbattery-1)
+     - [`<MediaDeviceSensor>`](./docs/MediaDeviceSensor.md), [`withMediaDevices()`](./docs/MediaDeviceSensor.md#withmediadevices), and [`@withMediaDevices`](./docs/MediaDeviceSensor.md#withmediadevices-1)
+     - [`<MediaSensor>`](./docs/MediaSensor.md), [`withMedia()`](./docs/MediaSensor.md#withmedia), and [`@withMedia`](./docs/MediaSensor.md#withmedia-1)
      - [`<NetworkSensor>`](./docs/NetworkSensor.md) and [`withNetwork()`](./docs/NetworkSensor.md#withnetwork)
      - [`<LightSensor>`](./docs/LightSensor.md)
      - [`<LocationSensor>`](./docs/LocationSensor.md)
      - [`<OrientationSensor>`](./docs/OrientationSensor.md) and [`withOrientation()`](./docs/OrientationSensor.md#withorientation)
      - [`<ScrollSensor>`](./docs/ScrollSensor.md)
      - [`<SizeSensor>`](./docs/SizeSensor.md)
-     - [`<ViewportSensor>`](./docs/ViewportSensor.md), `<ViewportScrollSensor>`, and `<ViewportObserverSensor>`
+     - [`<ViewportSensor>`](./docs/ViewportSensor.md), [`<ViewportScrollSensor>`](./docs/ViewportSensor.md#viewportscrollsensor), and [`<ViewportObserverSensor>`](./docs/ViewportSensor.md#viewportobserversensor)
      - [`<WidthSensor>`](./docs/WidthSensor.md)
      - [`<WindowScrollSensor>`](./docs/WindowScrollSensor.md)
      - [`<WindowSizeSensor>`](./docs/WindowSizeSensor.md)
   - Generators
      - [`<Alert>`](./docs/Alert.md)
-     - [`<Audio>`](./docs/Audio.md)
+     - [`<Audio>`](./docs/Audio.md), [`<Video>`](./docs/Video.md), and `<Media>`
      - [`<LocalStorage>`](./docs/LocalStorage.md)
      - `<Redirect>`
      - [`<Speak>`](./docs/Speak.md)
      - [`<Vibrate>`](./docs/Vibrate.md)
-     - `<Video>`
   - Context
-     - [`<Provider>`](./docs/context.md#provider), [`<Consumer>`](./docs/context.md#consumer), and [`withContext()`](./docs/context.md#withcontext)
-     - [`<Theme>`](./docs/theme.md#theme), [`<Themed>`](./docs/theme.md#themed), and [`withTheme()`](./docs/theme.md#withtheme)
+     - [`<Provider>`](./docs/context.md#provider), [`<Consumer>`](./docs/context.md#consumer), [`withContext()`](./docs/context.md#withcontext), and `@withContext`
+     - [`<Theme>`](./docs/theme.md#theme), [`<Themed>`](./docs/theme.md#themed), [`withTheme()`](./docs/theme.md#withtheme), and `@withTheme`
      - `<CssVars>`
-     - [`<Router>`](./docs/route.md#router), [`<Route>`](./docs/route.md#route), [`go()`](./docs/route.md#go), and [`withRoute()`](./docs/route.md#withroute)
+     - [`<Router>`](./docs/route.md#router), [`<Route>`](./docs/route.md#route), [`go()`](./docs/route.md#go), [`withRoute()`](./docs/route.md#withroute), and `@withRoute`
   - CSS resets
      - [`<CssResetEricMeyer>`](./docs/reset/CssResetEricMeyer.md)
      - [`<CssResetEricMeyerCondensed>`](./docs/reset/CssResetEricMeyerCondensed.md)

docs/Audio.md

@@ -36,6 +36,8 @@ interface IAudioProps {
   - `preload` - optional, string, `<audio>` element preload attribute.
   - `volume` - optional, number, audio volume in `[0..1]` range, defaults to `1`.
   - `noJs` - optional, React element(s) to render insided the `<audio>` tag.
+  - `onMount` - optional, callback, called when component mounts, receives `IAudio` as the first argument.
+  - `onUnmount` - optional, callback, called when component un-mounts, receives `IAudio` as the first argument.
 
 
 ## Arguments

docs/BatterySensor.md

@@ -1,12 +1,12 @@
-# `BatterySensor`
+# `<BatterySensor>`
 
 Uses [`Navigator.getBattery()`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/getBattery) API to track battery level, charging status and time it takes to charge/discharge a battery.
 
-# Props
+## Props
 
 None.
 
-# Example
+## Example
 
 ```jsx
 import {BatterySensor} from 'libreact/lib/BatterySensor';
@@ -26,3 +26,39 @@ Result
     "dischargingTime": null
 }
 ```
+
+## `withBattery()`
+
+Higher order component that injects `battery` prop into your component.
+
+```js
+import {withBattery} from 'libreact/lib/BatterySensor';
+
+const MyCompWithBattery = withBattery(MyComp);
+```
+
+Overwrite the inject prop name
+
+```js
+const MyCompWithBattery = withBattery(MyComp, 'myBattery');
+```
+
+or merge the props
+
+```js
+const MyCompWithBattery = withBattery(MyComp, null);
+```
+
+
+## `@withBattery`
+
+Stateful component class decorator that injects `battery` prop into your component.
+
+```js
+import {withBattery} from 'libreact/lib/BatterySensor';
+
+@withBattery
+class MyComp extends Component {
+
+}
+```

docs/MediaDeviceSensor.md

@@ -6,9 +6,34 @@ user's connected media devices.
 ## Usage
 
 ```jsx
-import {MediaDevicesSensor} from 'libreact/lib/MediaDevicesSensor';
+import {MediaDeviceSensor} from 'libreact/lib/MediaDeviceSensor';
 
-<MediaDevicesSensor>{(state) =>
+<MediaDeviceSensor>{(state) =>
   JSON.stringify(state, null, 4)
-}</MediaDevicesSensor>
+}</MediaDeviceSensor>
+```
+
+
+## `withMediaDevices()`
+
+Higher order component that injects `devices` prop into your component.
+
+```js
+import {withMediaDevices} from 'libreact/lib/MediaDeviceSensor';
+
+const MyCompDevices = withMediaDevices(MyComp);
+```
+
+
+## `@withMediaDevices`
+
+Stateful component class decorator that injects `devices` prop into your component.
+
+```js
+import {withMediaDevices} from 'libreact/lib/MediaDeviceSensor';
+
+@withMediaDevices
+class MyComp extends Component {
+
+}
 ```

docs/MediaSensor.md

@@ -11,3 +11,28 @@ import {MediaSensor} from 'libreact/lib/MediaSensor';
   `WIDTH IS GREATED THAN 480PX: ${matches}`
 }</MediaSensor>
 ```
+
+
+## `withMedia()`
+
+Higher order component that injects a boolean prop into your component that specifies if media query matches.
+
+```js
+import {withMedia} from 'libreact/lib/MediaSensor';
+
+const MyCompWithSize = withMedia(MyComp, 'isBigScreen', '(min-width: 480px)');
+```
+
+
+## `@withMedia`
+
+Stateful component class decorator that injects a boolean prop into your component that specifies if media query matches.
+
+```js
+import {withMedia} from 'libreact/lib/MediaSensor';
+
+@withMedia('isBigScreen', '(min-width: 480px)')
+class MyComp extends Component {
+
+}
+```

docs/Video.md

@@ -0,0 +1,123 @@
+# `<Video>`
+
+FaCC that creates a `<video>` element to play video media, re-renders on video state changes.
+
+## Usage
+
+```jsx
+import {Video} from 'libreact/lib/Video';
+
+<Video autoPlay src='http://dailym.ai/2rG7TBS'>{(actions, state) => {
+  JSON.stringify(state, null, 4)
+}}</Video>
+```
+
+
+## Props
+
+In addition to props below also accepts all [React's media events](https://reactjs.org/docs/events.html#media-events).
+
+```tsx
+interface IVideoProps {
+  src: string;
+  autoPlay?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  preload?: 'none' | 'metadata' | 'auto';
+  volume?: number;
+  noJs?: React.ReactElement<any>;
+}
+```
+
+  - `src` - required, string, video source file URL.
+  - `autoPlay` - optional, boolean, whether to autoplay media, defaults to `false`.
+  - `loop` - optional, boolean, whether to repeat the media when it ends, defaults to `false`.
+  - `muted` - optional, boolean, whether to mute the media, defaults to `false`.
+  - `preload` - optional, string, `<video>` element preload attribute.
+  - `volume` - optional, number, media volume in `[0..1]` range, defaults to `1`.
+  - `noJs` - optional, React element(s) to render insided the `<video>` tag.
+  - `onMount` - optional, callback, called when component mounts, receives `IVideo` as the first argument.
+  - `onUnmount` - optional, callback, called when component un-mounts, receives `IVideo` as the first argument.
+
+
+## Arguments
+
+The `children` function receives two arguments, first is the `IVideo` *actions* collection and the second
+is the state of the video component.
+
+```jsx
+<Video autoPlay src={src}>{({video, ...actions}, state) =>
+
+}</Video>
+```
+
+First argument is the `<Video>` component instance with the following public signature.
+
+```ts
+interface IVideo {
+  el: HTMLVideoElement;
+  video: React.ReactElement;
+  play();
+  pause();
+  seek(time: number);
+  volume(value: number);
+  mute();
+  unmute();
+}
+```
+
+, where
+
+  - `el` - `<video>` element DOM node.
+  - `video` - `<video>` element React node, that you have to insert in the JSX tree.
+
+The second argument is the state of the `<Video>` component with the following signature.
+
+```ts
+interface IVideoState {
+  buffered?: TRange[];
+  time?: number;
+  duration?: number;
+  isPlaying?: boolean;
+  muted?: boolean;
+  volume?: number;
+}
+
+type TRange = {
+  start: number;
+  end: number;
+};
+```
+
+, where
+
+  - `buffered` - a list of ranges representing media intervals that have been buffered by the browser.
+  - `time` - current time in seconds.
+  - `duration` - total video duration in seconds.
+  - `isPlaying` - whether the video is currently playing.
+  - `muted` - whether `muted` attribute is set on the video element.
+  - `volume` - current volume in range `[0..1]`.
+
+
+## Example
+
+Play a sample video.
+
+```jsx
+<Video
+  src='http://dailym.ai/2rG7TBS'
+  style={{
+    width: 400,
+    border: '1px solid tomato'
+  }}
+  render={({video, play, pause, seek, volume, mute, unmute}, {isPlaying}) =>
+    <div>
+      {video}
+      <br />
+      <button onClick={() => isPlaying ? pause() : play()}>
+        {isPlaying ? 'Pause' : 'Play'}
+      </button>
+    </div>
+  }
+/>
+```

docs/ViewportSensor.md

@@ -46,7 +46,16 @@ interface IViewportSensorState {
 }
 ```
 
+
 ## `<ViewportScrollSensor>`
 
+Is the same as `<ViewportSensor>`, but uses only window `scroll` event to check for visibility changes.
+
 The `<ViewportScrollSensor>` has an additional prop `throttle`, which is a number in milliseconds specifying
 how much to throttle document's `scroll` event.
+
+
+## `<ViewportObserverSensor>`
+
+Is the same as `<ViewportSensor>`, but uses only `IntersectionObserver` to detect element's intersection
+with viewport.

docs/libreact.png

@@ -1,6 +1,6 @@
 {
   "name": "libreact",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "React standard library",
   "main": "lib/index.js",
   "keywords": [