Merge branch 'master' into 47_provide_menu_fallback_items

.npmignore

@@ -1,5 +1,6 @@
 /node_modules/
 /.storybook/
+/docs/
 
 *.md
 *.yml

README.md

@@ -28,8 +28,9 @@ storiesOf("Some component name", module)
 
 Our target is to cover:
 * interaction with component via user actions mainly
-  * We use [Jest](https://facebook.github.io/jest/), as testing framework and [Enzyme](https://github.com/airbnb/enzyme) a testing utility which makes it easy to assert, manipulate, and traverse React Components' output.
-For assertions we use [Expect](https://github.com/mjackson/expect).
+  * We use [Jest](https://facebook.github.io/jest/), a testing framework with its own assertions.
+  * We use [Enzyme](https://github.com/airbnb/enzyme), a testing utility which makes it easy to render, manipulate, and traverse React Components' output.
+  * We use [Sinon](https://github.com/sinonjs/sinon/) to mock API calls and spy on methods expected to be triggered.
 * component layout at it's lifecycle different states
   * This can be achieved via [Storybook storyshots](https://github.com/storybooks/storybook/tree/master/addons/storyshots) and [Jest snapshots](https://facebook.github.io/jest/docs/en/snapshot-testing.html)
 
@@ -58,6 +59,8 @@ Ensure packages are installed with correct version numbers by running:
 import { Footer, FileUp } from '@comicrelief/storybook';
 ```
 
+In some cases there is documentation for a specific component in a `README.md` inside its own directory.
+
 ### Semantic Release Process
 
 Git commit messages are used to automatically publish a new version of npm package. To achieve this, **every commit message** should have a **type** and a **message** in the format described below.

src/components/SchoolsLookUp/README.md

@@ -0,0 +1,29 @@
+# SchoolsLookUp
+> A component responsible for handling Edco lookup.
+
+![data flow](./../../../docs/school%20lookup%20data%20flow.png?raw=true "Data Flow")
+
+### Why don't we save data directly inside SchoolsLookUp?
+* Data in that case could be from an EdCo-selected school result or a manually entered one.
+* We are already saving school details outside the component, so it felt redundant to save the details inside the component at the same time.
+
+### Why do we have multiple methods dedicated to rendering?
+* We have a lot of fields that are displayed at different cases which led to a big render method, but redundancy can be spotted.
+* To minimise redundancy, we can move any repetitive snippet into a method and just reuse it saving space and enhancing readability.
+
+### Why do we have a lot of props?
+* We need to avoid static attributes and provide some flexibility to the container.
+* For instance, we may need to set input id and name, so it's better to have that as a prop.
+* Sometimes an optional prop with a default value is a better option, so that whenever it is not needed, we don't have to pass it.
+
+### How are fields validated?
+* Validation logic itself does not exist inside the `SchoolsLookUp` component, as that's not the component's own responsibility.
+* A validation trigger is inserted into the component, to be executed whenever a change occurs.
+* Error messages are passed from the outer scope into the component to be displayed there.
+
+![container](./../../../docs/school%20lookup%20container.png?raw=true "Container")
+
+### Why do we need SchoolsLookUpContainer?
+* `SchoolsLookUp` needed to be re-rendered in order to notice new values passed via props.
+* Storybook loaded the component once, and ignores whatever changes occur later.
+* State can re-render `SchoolsLookUp`, when it changes - more info on [state and lifecycle here](https://reactjs.org/docs/state-and-lifecycle.html).