Add InputField documentation

components/Form/FormComponents.css

@@ -1,3 +1,6 @@
+/**
+ * TODO: Remove this as it breaks convention of preferring `[margin|padding]-top`
+ */
 .field {
   padding-bottom: var(--size-lg-i);
 }

components/Form/FormComponents.js

@@ -74,10 +74,12 @@ export const InputWrapper = ({ className, children }) => (
 const sharedPropTypes = {
   className: PropTypes.string,
   children: PropTypes.node,
-  error: PropTypes.string,
 };
 
-Field.propTypes = sharedPropTypes;
+Field.propTypes = {
+  ...sharedPropTypes,
+  error: PropTypes.string,
+};
 Meta.propTypes = sharedPropTypes;
 Description.propTypes = sharedPropTypes;
 Label.propTypes = {

globals/breakpoints.css

@@ -14,6 +14,7 @@
   @custom-media --modal-lg (min-width: 37.5rem);
 
   /* style-guide */
+  @custom-media --scaffold-dl-lg-i (min-width: 30rem);
   @custom-media --colors-2up (min-width: 25rem);
   @custom-media --colors-3up (min-width: 50rem);
   @custom-media --iconography-3up (min-width: 31.875rem);

styleguide/components/Navigation/Navigation.js

@@ -110,6 +110,17 @@ const Navigation = ({ className, onLinkClick }) => (
             Inputs
           </NavLink>
         </li>
+        <li className={ css.linkListItem }>
+          <NavLink
+            exact
+            activeClassName={ css.linkActive }
+            className={ css.link }
+            to="/patterns/input-field"
+            onClick={ onLinkClick }
+          >
+            InputField
+          </NavLink>
+        </li>
         <li className={ css.linkListItem }>
           <NavLink
             exact

styleguide/components/Scaffold/Scaffold.css

@@ -46,3 +46,34 @@
 .link:hover {
   color: var(--color-primary--light);
 }
+
+.descriptionList {
+  display: flex;
+  flex-wrap: wrap;
+}
+
+.descriptionList dt {
+  font-weight: var(--fontweight-demi);
+  display: block;
+  flex-basis: 100%;
+  margin-top: var(--size-sm-ii);
+}
+
+.descriptionList dd {
+  display: block;
+  margin: 0;
+  padding: 0;
+  flex-basis: 100%;
+}
+
+@media(--scaffold-dl-lg-i) {
+  .descriptionList dt {
+    flex-basis: 30%;
+  }
+
+  .descriptionList dd {
+    flex-basis: 70%;
+    padding-left: var(--size-regular);
+    margin-top: var(--size-sm-ii);
+  }
+}

styleguide/components/Scaffold/Scaffold.js

@@ -17,6 +17,7 @@ export const body = css.body;
 export const section = m.mtLgIii;
 export const code = css.code;
 export const link = css.link;
+export const descriptionList = css.descriptionList;
 
 export const H = ({ level, className, children }) => createElement(
   `h${level}`,
@@ -54,6 +55,12 @@ export const A = ({ className, children, ...rest }) => (
   <a { ...rest } className={ cx(link, className) }>{ children }</a>
 );
 
+export const Dl = ({ className, children, ...rest }) => (
+  <dl { ...rest } className={ cx(descriptionList, className) }>
+    { children }
+  </dl>
+);
+
 H.propTypes = {
   ...propTypes,
   level: PropTypes.number,
@@ -65,10 +72,9 @@ T.propTypes = {
 };
 
 C.propTypes = propTypes;
-
 A.propTypes = propTypes;
-
 D.propTypes = propTypes;
+Dl.propTypes = propTypes;
 
 H.defaultProps = {
   level: 1,

styleguide/screens/Patterns/InputField/InputField.js

@@ -0,0 +1,123 @@
+import React from 'react';
+import cx from 'classnames';
+import dedent from 'dedent';
+
+import Specimen from '../../../components/Specimen/Specimen';
+import { D, H, T, Dl, A, C } from '../../../components/Scaffold/Scaffold';
+
+import FunnelInputField from '../../../../components/FunnelInputField/FunnelInputField';
+import Input from '../../../../components/Form/Input/Input';
+
+import m from '../../../../globals/modifiers.css';
+
+const InputFieldDocumentation = () => (
+  <div>
+    <H level={ 1 }>InputField</H>
+    <T elm="p" className={ cx(m.mtr, m.largeI, m.demi) }>
+      An <C>InputField</C> combines multiple elements that may be required when using
+      any given input. It gives you the flexibility to build out your forms in
+      many different ways.
+    </T>
+    <D>
+      <Specimen
+        classNames={ {
+          root: m.mtr,
+          specimenContainer: m.par,
+        } }
+        code={ dedent`
+          <FunnelInputField
+            id="example"
+            meta="Meta data"
+            label="Label"
+            optionalLabel="optional"
+            valueReplay="Value replay"
+            description="Description/helper text"
+          >
+            <Input value="Input component" />
+          </FunnelInputField>
+        ` }
+      >
+        <FunnelInputField
+          id="example"
+          meta="Meta data"
+          label="Label"
+          optionalLabel="optional"
+          valueReplay="Value replay"
+          description="Description/helper text"
+        >
+          <Input value="Input component" />
+        </FunnelInputField>
+      </Specimen>
+    </D>
+    <D>
+      <T elm="p">
+        Each property on the <C>InputField</C> has a specific purpose. They should be used like so:
+      </T>
+      <Dl className={ m.mtr }>
+        <T elm="dt">
+          Meta data
+        </T>
+        <T elm="dd">
+          Should provide the user with non-critical, but useful information.
+          E.g., “Question 1 of 5”.
+        </T>
+        <T elm="dt">
+          Label
+        </T>
+        <T elm="dd">
+          Is the caption for the input. It should provide the user enough
+          information as the expected value of the input. E.g., “First name”.
+        </T>
+        <T elm="dt">
+          Optional
+        </T>
+        <T elm="dd">
+          This tells the user whether or not the input is optional. As the
+          majority of our inputs are mandatory, we’ve opted to display for
+          edge cases and not the majority.
+        </T>
+        <T elm="dt">
+          Value replay
+        </T>
+        <T elm="dd">
+          This property can be used to repeat the current value of the
+          input. This is useful in scenarios where the input is not clear,
+          such as with an InputRange. E.g., “£150 - 800”.
+        </T>
+        <T elm="dt">
+          Description/helper text
+        </T>
+        <T elm="dd">
+          Use this to provide the user with additional information as to
+          what is expected of them, such as validation rules. E.g.,
+          “8 characters minimum”. This is placed below the label as it is
+          supporting material. The solid break gives distinction to both
+          elements, and avoids overflow across multiple lines.
+        </T>
+        <T elm="dt">
+          Input component
+        </T>
+        <T elm="dd">
+          The input field component accepts our <A href="/patterns/inputs">input
+          components</A> as it’s child.
+        </T>
+      </Dl>
+    </D>
+    <D>
+      <H level={ 2 }>Usage</H>
+      <T elm="p" className={ m.mtr }>
+        When using <C>InputField</C>, be careful not to over complicate
+        the interface by using <strong>too many</strong> of the available
+        properties. At minimum, you should include a label and input. From there,
+        add additional elements when necessary.
+      </T>
+      <T elm="p" className={ m.mtr }>
+        When the only elements on the page are a series of
+        <C>InputField</C> components, having them left-aligned may not
+        be appropriate. In this case, center it.
+      </T>
+    </D>
+  </div>
+);
+
+export default InputFieldDocumentation;

styleguide/screens/Patterns/InputField/InputField.test.js

@@ -0,0 +1,9 @@
+import React from 'react';
+import { render } from 'react-dom';
+
+import InputField from './InputField';
+
+it('renders without crashing', () => {
+  const div = document.createElement('div');
+  render(<InputField />, div);
+});

styleguide/screens/Patterns/Patterns.js

@@ -4,6 +4,7 @@ import { Switch, Route } from 'react-router-dom';
 import Accessibility from './Accessibility/Accessibility';
 import Badge from './Badge/Badge';
 import Buttons from './Buttons/Buttons';
+import InputField from './InputField/InputField';
 import Inputs from './Inputs/Inputs';
 import LeftRight from './LeftRight/LeftRight';
 import Markdown from './Markdown/Markdown';
@@ -14,6 +15,7 @@ const Patterns = () => (
     <Route path="/patterns/accessibility" component={ Accessibility } />
     <Route path="/patterns/badge" component={ Badge } />
     <Route path="/patterns/buttons" component={ Buttons } />
+    <Route path="/patterns/input-field" component={ InputField } />
     <Route path="/patterns/inputs" component={ Inputs } />
     <Route path="/patterns/leftright" component={ LeftRight } />
     <Route path="/patterns/markdown" component={ Markdown } />