Merge pull request #6 from MailOnline/feat/location

Feat/location

Author: streamich

.npmrc

@@ -1,28 +1,28 @@
-# mol-fe-react
+# libreact
 
-React utility belt.
+React standard library, must-have toolbox for any React project.
 
-  - Collection of React goodies
-  - Isomorphic - all components work in browser and Node
-  - [See demos and docs](https://mailonline.github.io/mol-fe-react/)
+  - Collection of React sensors, FaCCs, HOCs, context, lazy loading, 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/).
 
 ## Installation
 
 ```shell
-npm install mol-fe-react --save
+npm install libreact --save
 ```
 
 ## Usage
 
 Import each utility individually to decrease your bundle size
 
 ```js
-import {mock} from 'mol-fe-react/lib/mock';
+import {mock} from 'libreact/lib/mock';
 
 const MyComponent = mock();
 ```
 
-## Reference
+## Contents
 
   - Dummies
      - [`mock()`](./docs/mock.md)
@@ -31,25 +31,30 @@ const MyComponent = mock();
      - [`delayed()`](./docs/delayed.md)
      - [`invert()`](./docs/invert.md)
   - Sensors
-     - [`<SizeSensor>`](./docs/SizeSensor.md)
-     - [`<WidthSensor>`](./docs/WidthSensor.md)
-     - [`<ScrollSensor>`](./docs/ScrollSensor.md)
+     - [`<BatterySensor>`](./docs/BatterySensor.md)
+     - [`<MediaDeviceSensor>`](./docs/MediaDeviceSensor.md)
      - [`<MediaSensor>`](./docs/MediaSensor.md)
-     - [`<WindowSizeSensor>`](./docs/WindowSizeSensor.md)
-     - [`<WindowScrollSensor>`](./docs/WindowScrollSensor.md)
      - [`<NetworkSensor>`](./docs/NetworkSensor.md) and [`withNetwork()`](./docs/NetworkSensor.md#withnetwork)
-     - [`<BatterySensor>`](./docs/BatterySensor.md)
      - [`<LightSensor>`](./docs/LightSensor.md)
-     - [`<MediaDeviceSensor>`](./docs/MediaDeviceSensor.md)
+     - [`<LocationSensor>`](./docs/LocationSensor.md)
+     - [`<ScrollSensor>`](./docs/ScrollSensor.md)
+     - [`<SizeSensor>`](./docs/SizeSensor.md)
+     - `<ViewportSensor>`
+     - [`<WidthSensor>`](./docs/WidthSensor.md)
+     - [`<WindowScrollSensor>`](./docs/WindowScrollSensor.md)
+     - [`<WindowSizeSensor>`](./docs/WindowSizeSensor.md)
   - Generators
+     - [`<Audio>`](./docs/Audio.md)
+     - [`<LocalStorage>`](./docs/LocalStorage.md)
+     - `<Redirect>`
      - [`<Speak>`](./docs/Speak.md)
      - [`<Vibrate>`](./docs/Vibrate.md)
-     - [`<LocalStorage>`](./docs/LocalStorage.md)
-     - [`<Audio>`](./docs/Audio.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)
      - `<CssVars>`
+     - [`<Router>`](./docs/route.md#router), [`<Route>`](./docs/route.md#route), [`go()`](./docs/route.md#go), and [`withRoute()`](./docs/route.md#withroute)
   - CSS resets
      - [`<CssResetEricMeyer>`](./docs/reset/CssResetEricMeyer.md)
      - [`<CssResetEricMeyerCondensed>`](./docs/reset/CssResetEricMeyerCondensed.md)

README.md

@@ -5,19 +5,20 @@ FaCC that creates an `<audio>` element to play audio tracks, re-renders on audio
 ## Usage
 
 ```jsx
-import {Audio} from 'mol-fe-react/lib/Audio';
+import {Audio} from 'libreact/lib/Audio';
 
 <Audio autoPlay src='https://www.soundhelix.com/examples/mp3/SoundHelix-Song-2.mp3'>{(control, state) => {
   JSON.stringify(state, null, 4)
 }}</Audio>
 ```
 
+
 ## Props
 
 In addition to props below also accepts all [React's media events](https://reactjs.org/docs/events.html#media-events).
 
 ```tsx
-export interface IAudioProps {
+interface IAudioProps {
   src: string;
   autoPlay?: boolean;
   loop?: boolean;
@@ -36,6 +37,56 @@ export interface IAudioProps {
   - `volume` - optional, number, audio volume in `[0..1]` range, defaults to `1`.
   - `noJs` - optional, React element(s) to render insided the `<audio>` tag.
 
+
+## Arguments
+
+The `children` function receives two arguments, `audio` instance as *controller* and `state`.
+
+```jsx
+<Audio autoPlay src={src}>{(audio, state) =>
+
+}</Audio>
+```
+
+First argument is the `<Audio>` component instance with the following public signature.
+
+```ts
+interface IAudio {
+  el: HTMLAudioElement;
+  play();
+  pause();
+  seek(time: number);
+  volume(value: number);
+  mute();
+  unmute();
+}
+```
+
+, where
+
+  - `el` - `<audio>` element DOM node.
+
+The second argument is the state of the `<Audio>` component with the following signature.
+
+```ts
+interface IAudioState {
+  time?: number;
+  duration?: number;
+  isPlaying?: boolean;
+  muted?: boolean;
+  volume?: number;
+}
+```
+
+, where
+
+  - `time` - current time in seconds.
+  - `duration` - total audio track duration in seconds.
+  - `isPlaying` - whether the audio track is currently playing.
+  - `muted` - whether `muted` attribute is set on the audio element.
+  - `volume` - current volume in range `[0..1]`.
+
+
 ## Example
 
 Play a sample audio track with control buttons.

docs/Audio.md

@@ -0,0 +1,42 @@
+# `<LocationSensor>`
+
+FaCC that uses [`Window.location`](https://developer.mozilla.org/en-US/docs/Web/API/Window/location)  and
+[`Window.history`](https://developer.mozilla.org/en-US/docs/Web/API/Window/history) APIs to track
+page location and re-render on any changes.
+
+## Usage
+
+```jsx
+import {LocationSensor} from 'libreact/lib/LocationSensor';
+
+<LocationSensor>{(location) =>
+  <pre style={{fontFamily: 'monospace'}}>
+    {JSON.stringify(location, null, 4)}
+  </pre>
+}</LocationSensor>
+```
+
+## Props
+
+None.
+
+## Reference
+
+Returns location state object with the following signature
+
+```ts
+interface ILocationSensorState {
+  trigger: string;
+  state?: any;
+  length?: number;
+  hash?: string;
+  host?: string;
+  hostname?: string;
+  href?: string;
+  origin?: string;
+  pathname?: string;
+  port?: string;
+  protocol?: string;
+  search?: string;
+}
+```

docs/LocationSensor.md

@@ -5,7 +5,7 @@ FaCC that re-renders on network status change. Uses `navigator.onLine` and [`Net
 
 ## `<NetworkSensor>`
 
-FaCC that passes through its state to child function
+Passes through its state to the `children` function
 
 ```ts
 interface INetworkSensorState {
@@ -28,8 +28,8 @@ None.
 ```jsx
 import {NetworkSensor} from 'mol-fe-react/lib/NetworkSensor';
 
-<NetworkSensor>{(status) =>
-  JSON.strinfigy(status, null 4)
+<NetworkSensor>{(state) =>
+  JSON.strinfigy(state, null 4)
 }</NetworkSensor>
 ```
 
@@ -52,7 +52,7 @@ Result
   - `downlink`, `downlinkMax`, `effectiveType`, `type`, `rtt` - properties as provided by [`NetworkInformation`](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation).
 
 
-## `withNetwork`
+## `withNetwork()`
 
 HOC that merges `<NetworkSensor>` state into props of the enhanced component.
 
@@ -61,9 +61,13 @@ HOC that merges `<NetworkSensor>` state into props of the enhanced component.
 ```jsx
 import {withNetwork} from 'mol-fe-react/lib/NetworkSensro';
 
-const NetworkStatus = withNetwork((props) =>
+const NetworkStatusFormatter = (props) =>
   <pre style={{fontFamily: 'monospace'}}>
     {JSON.stringify(props, null, 4)}
-  </pre>
+  </pre>;
+
+const NetworkStatus = withNetwork(NetworkStatusFormatter);
+
+<NetworkStatus />
 );
 ```

docs/NetworkSensor.md

@@ -8,6 +8,8 @@ Create a mock React component whose implementation can be postponed.
 Create a mock and implement it
 
 ```js
+import {mock} from 'libreact/lib/mock';
+
 const Player = mock();
 
 // Now you can already use <Player>.
@@ -28,17 +30,16 @@ const MySvg = mock({
 ## Reference
 
 ```ts
-const mock: <TProps>(params?: ImockParams) => IMockConstructor<TProps>;
+mock: (params?: IMockParams) => IMockComponent;
 
-interface ImockParams {
-  loading?: React.ReactElement<any>;
+interface IMockParams {
+  loading?: React.ReactElement;
 }
 
-interface IMockComponent<TProps> {
-  new (props: TProps, context): IMock<TProps>;
-  implement(Implementation: React.Component<TProps, any> | React.SFC<TProps>);
+interface IMockComponent {
+  implement(Implementation: React.Component | React.SFC);
 }
 ```
 
-  - `loading` - React element to show while the is not implemented.
+  - `loading` - React element to show while the mock is not implemented.
   - `.implement` - use this method to set the implementation of your mock coponent.