From fbb69b09ba327bc8871cd46d874b301e694b370e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rasmus=20W=C3=B8lk?=
 <640976+rasmuswoelk@users.noreply.github.com>
Date: Fri, 31 May 2019 17:13:42 +0200
Subject: [PATCH] <Checkbox> refactoring and STCOM-529 (vertical label) (#974)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Added 'vertical'-prop for Checkbox which makes it possible to render the label above the checkbox. This change required both structural and style changes. While making the changes I did some minor refactoring and cleaned up the CSS a bit. Updated FilterGroups to match the changes for Checkbox. Added label margin as a variable because I needed to reference it within the Checkbox-component. Also updated Checkbox examples to display a vertical example.

* Only apply the 'for'-prop on the root <label>-element if a 'label'-prop is present. This allows for a checkbox to be rendered inline without a label which makes it possible to render an external label-element and link the two using the 'for'-attribute on the label with the ID of the checkbox. This ensures that there's no double for-attributes which can confuse screen readers. Also added an example for this in Storybook.

* Added readme (WIP)

* Minor readme changes, fixed basic usage example and more clean up and refactoring of the <Checkbox>-component

* Removed obsolete 'labelStyle'-prop

* Removed obsolete 'hover'-prop

* Removed obsolete prop 'marginBottom0'

* Fixed Checkbox tests

* Added inputRef-prop for Checkbox with a corresponding test.

* Updated storybook example

* Warning/error messages were rendered next to the checkbox/label which looked odd in tight spaced UI's. Instead, I changed the feedback messages to be rendered below the checkbox/label like other form elements.

* Further Storybook examples cleanup. Removed some unnecessary logic that could make the exmaples more confusing

* Removed .only from tests

* Updated warning color because it's contrast ratio with a white background was insufficient according to WCAG standards.

* Minor linting fix and removed name from checkboxes in storybook example

* Updated readme

* Setting checkbox as 'inline' if there's no label.

* Updated sr-only helper class after experiencing a weird bug in the stripes-platform when clicking a checkbox

* Renamed some class names, added 'innerClass'-prop which is needed to properly style the FilterGroups component checkboxes and updated the readme

* Fixed tests

* Simplified feedback rendering logic

* Updated readme

* Added additional tests

* Only render a <label> if there's a label to show. Changed poitioning of the input element so that it's on top of the custom checkbox but hidden with opacity: 0; With this change we no longer have any accessibility issues with double label's if a developer uses a checkbox with an external <label>

* Utilized the 'tagName'-prop on the <Label>-component instead of setting a conditional on a separate Element constant.

* Fixed tests and added additional tests. Test coverage is now 100% 🎉

* Removed .only from tests and added 'storybook-static' to eslintignore (it was causing linting to run very slowly and potentially never finish)
---
 .eslintignore                       |   1 +
 lib/Checkbox/Checkbox.css           | 207 +++++++++++++-------------
 lib/Checkbox/Checkbox.js            | 218 +++++++++++++++-------------
 lib/Checkbox/readme.md              |  73 +++++++++-
 lib/Checkbox/stories/BasicUsage.js  | 187 ++++++++++++------------
 lib/Checkbox/tests/Checkbox-test.js | 121 ++++++++++++++-
 lib/Checkbox/tests/interactor.js    |  18 ++-
 lib/FilterGroups/FilterGroups.css   |   9 +-
 lib/FilterGroups/FilterGroups.js    |   3 +-
 lib/Label/Label.css                 |   2 +-
 lib/global.css                      |   2 +
 lib/variables.css                   |   3 +-
 12 files changed, 524 insertions(+), 320 deletions(-)

diff --git a/.eslintignore b/.eslintignore
index 841de086c..fc2805bac 100644
--- a/.eslintignore
+++ b/.eslintignore
@@ -1,2 +1,3 @@
 /artifacts
 /node_modules
+/storybook-static
\ No newline at end of file
diff --git a/lib/Checkbox/Checkbox.css b/lib/Checkbox/Checkbox.css
index 2791ce6cb..064e43836 100644
--- a/lib/Checkbox/Checkbox.css
+++ b/lib/Checkbox/Checkbox.css
@@ -6,57 +6,28 @@
 
 .checkbox {
   display: flex;
+  flex-direction: column;
   position: relative;
   color: var(--color-text);
   line-height: var(--line-height);
+  margin-bottom: 0;
 
   &.fullWidth {
     width: 100%;
   }
-
-  &.marginBottom0 {
-    margin-bottom: 0;
-  }
-
-  /**
-   * Inline checkbox
-   */
-  &.inline {
-    display: inline-flex;
-
-    /**
-     * If we only render the checkbox (no label)
-     */
-
-    &.noLabel {
-      height: auto;
-
-      & label.checkboxLabel {
-        height: auto;
-        padding: 6px;
-        margin: 0;
-
-        &::before {
-          left: 0;
-          right: 0;
-        }
-      }
-    }
-  }
-}
-
-/* Apply spacing between inline checkboxes when stacked */
-.inline + .inline {
-  margin-left: var(--gutter-static-two-thirds);
-  margin-right: 0;
 }
 
-[dir="rtl"] .inline + .inline {
-  margin-right: var(--gutter-static-two-thirds);
-  margin-left: 0;
+/**
+ * Label
+ */
+.label {
+  margin-bottom: 0;
 }
 
-.labelCheck {
+/**
+ * Custom checkbox styling
+ */
+.checkboxIcon {
   position: relative;
   width: var(--checkbox-size);
   height: var(--checkbox-size);
@@ -66,31 +37,103 @@
   display: flex;
   overflow: hidden;
   flex-shrink: 0;
-  top: 1px;
 
   & svg {
     opacity: 0;
+  }
+}
+
+.inner {
+  min-height: var(--control-min-size-desktop);
+  display: flex;
+  align-items: baseline;
+  cursor: pointer;
+  flex-grow: 2;
+  position: relative;
+  border-radius: var(--radius);
+  font-size: var(--font-size-medium);
+}
+
+/**
+ * Label text
+ */
+.labelText {
+  margin: 0 0 0 var(--gutter-static-one-third);
+  display: flex;
+  align-items: center;
+  min-height: var(--control-min-size-desktop);
+}
+
+[dir="rtl"] .labelText {
+  margin: 0 var(--gutter-static-one-third) 0 0;
+}
+
+/**
+ * Input
+ */
+.input {
+  position: absolute;
+  z-index: 10;
+  opacity: 0;
+  cursor: pointer;
+}
+
+.noLabel .input {
+  transform: scale(1.9);
+}
+
+/**
+ * Vertical label alignment
+ */
+.vertical .label {
+  flex-direction: column;
+  align-items: flex-start;
+
+  & .labelText {
+    margin: 0 0 var(--control-label-margin-bottom) 0;
+    min-height: 0;
+  }
 
-    & path {
-      stroke: #000;
-    }
+  & .inner {
+    align-items: center;
   }
 }
 
+/**
+ * Inline checkbox
+ */
+.inline {
+  display: inline-flex;
+
+  &.noLabel .inner {
+    align-items: center;
+  }
+}
+
+/* Apply spacing between inline checkboxes when stacked */
+.inline + .inline {
+  margin-left: var(--gutter-static-two-thirds);
+  margin-right: 0;
+}
+
+[dir="rtl"] .inline + .inline {
+  margin-right: var(--gutter-static-two-thirds);
+  margin-left: 0;
+}
+
 /**
  * Checkbox feedback
  */
 .checkboxFeedback {
-  font-size: var(--font-size-small);
+  font-size: var(--font-size-medium);
 }
 
-/* Warning and error states */
 .hasWarning {
   & .checkboxFeedback {
     color: var(--warn);
   }
 
-  & .labelCheck {
+  & .checkboxIcon {
     border-color: var(--warn);
   }
 }
@@ -100,30 +143,16 @@
     color: var(--error);
   }
 
-  & .labelCheck {
+  & .checkboxIcon {
     border-color: var(--error);
   }
 }
 
-.checkboxLabel {
-  padding: var(--input-vertical-padding) 0;
-  display: flex;
-  align-items: baseline;
-  cursor: pointer;
-  flex-grow: 2;
-  position: relative;
-  border-radius: var(--radius);
-  font-size: var(--font-size-medium);
-  margin-bottom: 0;
-
-  &.disabledLabel {
-    cursor: not-allowed;
-    color: var(--color-text-p2);
-
-    & .labelCheck {
-      opacity: 0.5;
-    }
-  }
+/**
+ * Interaction styles (hover, focus, active)
+ */
+.checkboxInteractionStylesControl {
+  composes: interactionStylesControl from "../sharedStyles/interactionStyles.css";
 }
 
 .checkboxInteractionStyles {
@@ -134,48 +163,24 @@
   composes: isFocused from "../sharedStyles/interactionStyles.css";
 }
 
-.formLabel {
-  composes: checkboxLabel;
-  font-weight: bold;
-  text-transform: Uppercase;
-}
-
-.labelText {
-  margin: 0 0 0 var(--gutter-static-one-third);
-  display: flex;
-  align-items: center;
-  min-height: var(--control-min-size-desktop);
-}
-
-[dir="rtl"] .labelText {
-  margin: 0 var(--gutter-static-one-third) 0 0;
-}
-
-/* fix for shrinkage issues with checkbox as a flex-child */
-:global input[type='checkbox'] {
-  min-width: 16px;
-}
-
 /**
- * Custom input styling
+ * Disabled
  */
-input.checkboxInput {
-  margin: 0 9px;
-  margin-bottom: 2px;
-  position: absolute;
-  clip: rect(1px, 1px, 1px, 1px);
-  z-index: -1;
-}
+.disabled {
+  & .checkboxIcon {
+    opacity: 0.5;
+  }
 
-/* disabled styles */
-.checkboxInput:disabled .labelCheck {
-  opacity: 0.65;
+  &:hover .inner {
+    cursor: default;
+  }
 }
 
 /**
  * Checked state
  */
-.checkboxInput:checked + .labelCheck {
+
+.input:checked + .checkboxIcon {
   background-color: #000;
 
   & svg {
diff --git a/lib/Checkbox/Checkbox.js b/lib/Checkbox/Checkbox.js
index 989f95ddd..1fd88531c 100644
--- a/lib/Checkbox/Checkbox.js
+++ b/lib/Checkbox/Checkbox.js
@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { createRef } from 'react';
 import PropTypes from 'prop-types';
 import classNames from 'classnames';
 import uniqueId from 'lodash/uniqueId';
@@ -22,13 +22,11 @@ class Checkbox extends React.Component {
     disabled: PropTypes.bool,
     error: PropTypes.node,
     fullWidth: PropTypes.bool,
-    hover: PropTypes.bool,
     id: PropTypes.string,
     inline: PropTypes.bool,
+    inputRef: PropTypes.oneOfType([PropTypes.object, PropTypes.func]),
     label: PropTypes.node,
     labelClass: PropTypes.string,
-    labelStyle: PropTypes.object,
-    marginBottom0: PropTypes.bool,
     name: PropTypes.string,
     onBlur: PropTypes.func,
     onChange: PropTypes.func,
@@ -39,85 +37,84 @@ class Checkbox extends React.Component {
       PropTypes.bool,
       PropTypes.string
     ]),
+    vertical: PropTypes.bool,
     warning: PropTypes.node,
   };
 
+  static defaultProps = {
+    vertical: false,
+  };
+
   constructor(props) {
     super(props);
-
-    this.state = {
-      inputInFocus: false
-    };
-
     this.id = this.props.id || uniqueId('checkbox-');
 
-    this.handleChange = this.handleChange.bind(this);
-    this.handleFocus = this.handleFocus.bind(this);
-    this.handleBlur = this.handleBlur.bind(this);
-    this.getFeedbackClasses = this.getFeedbackClasses.bind(this);
-    this.getFeedbackElement = this.getFeedbackElement.bind(this);
+    // Typecheck for ref callbacks
+    if (typeof props.inputRef === 'function') {
+      this.input = (ref) => {
+        props.inputRef(ref);
+        this.input.current = ref;
+      };
+    } else {
+      this.input = props.inputRef || createRef();
+    }
   }
 
-  getLabelStyle() {
+  state = {
+    inputInFocus: false
+  };
+
+  getInnerClasses = () => {
+    const { inputInFocus } = this.state;
+    const { disabled, innerClass } = this.props;
+
     return classNames(
-      css.checkboxLabel,
-      { [css[this.props.labelStyle]]: !this.props.labelClass && this.props.labelStyle },
-      { [css.checkboxInteractionStyles]: !this.props.disabled },
-      { [css.disabledLabel]: this.props.disabled },
-      { [css.labelFocused]: this.state.inputInFocus },
-      this.props.labelClass,
+      css.inner,
+      { [css.checkboxInteractionStyles]: !disabled },
+      { [css.disabledLabel]: disabled },
+      { [css.labelFocused]: inputInFocus },
+      innerClass,
     );
   }
 
-  getRootStyle() {
+  getRootClasses = () => {
+    const { className, fullWidth, vertical, label, disabled, inline, error, warning } = this.props;
+
     return classNames(
       [`${css.checkbox}`],
-      { [`${css.noLabel}`]: !this.props.label },
-      { [`${css.hover}`]: this.props.hover },
-      { [`${css.hovered}`]: (this.props.hover && this.state.inputInFocus) },
-      { [`${css.fullWidth}`]: this.props.fullWidth },
-      { [`${css.marginBottom0}`]: this.props.marginBottom0 },
-      { [`${css.inline}`]: this.props.inline },
-      this.props.className,
-      this.getFeedbackClasses(),
+      { [`${css.fullWidth}`]: fullWidth },
+      { [`${css.inline}`]: inline || vertical || !label },
+      { [`${css.vertical}`]: vertical },
+      { [`${css.disabled}`]: disabled },
+      { [`${css.noLabel}`]: !label },
+      { [`${css.hasError}`]: !!error },
+      { [`${css.hasWarning}`]: !!warning },
+      className,
     );
   }
 
-  // Add feedback class on warning or error
-  getFeedbackClasses() {
-    const { warning, error } = this.props;
-    const classes = [];
-
-    // Check if checkbox has error or warning
-    if (error) {
-      classes.push(css.hasError);
-    } else if (warning) {
-      classes.push(css.hasWarning);
-    }
-
-    // Add the feedback class if we have feedback classes
-    if (classes.length) {
-      classes.push(css.hasFeedback);
-    }
+  getLabelClasses = () => {
+    const { disabled, labelClass } = this.props;
 
-    return classes;
+    return classNames(
+      [`${css.label}`],
+      { [css.checkboxInteractionStylesControl]: !disabled },
+      labelClass,
+    );
   }
 
-  // Get feedback element (if the checkbox has any feedback to show)
-  getFeedbackElement() {
-    const hasFeedback = !!this.getFeedbackClasses().length;
+  renderFeedbackElement = () => {
+    const { error, warning } = this.props;
+    const hasFeedback = error || warning;
+
     if (!hasFeedback) {
       return false;
     }
 
-    const error = this.props.error;
-    const warning = this.props.warning;
-
-    // Currently prefering error over warning
     return (<div className={css.checkboxFeedback}>{error || warning}</div>);
   }
 
-  handleChange(e) {
+  handleChange = (e) => {
     const { readOnly, onChange } = this.props;
 
     // Disable onChange handler if the field is read-only
@@ -128,7 +125,7 @@ class Checkbox extends React.Component {
     }
   }
 
-  handleFocus(e) {
+  handleFocus = (e) => {
     this.setState({
       inputInFocus: true,
     });
@@ -138,7 +135,7 @@ class Checkbox extends React.Component {
     }
   }
 
-  handleBlur(e) {
+  handleBlur = (e) => {
     this.setState({
       inputInFocus: false,
     });
@@ -148,6 +145,24 @@ class Checkbox extends React.Component {
     }
   }
 
+  renderLabelText = () => {
+    const { label, required, readOnly } = this.props;
+
+    return (
+      <span className={css.labelText}>
+        { label }
+        { required && <Asterisk /> }
+        { readOnly && (
+          <Icon size="small" icon="lock">
+            <span className="sr-only">
+              <FormattedMessage id="stripes-components.readonly" />
+            </span>
+          </Icon>
+        ) }
+      </span>
+    );
+  }
+
   render() {
     const {
       autoFocus,
@@ -157,62 +172,57 @@ class Checkbox extends React.Component {
       name,
       readOnly,
       required,
-      value
+      value,
+      vertical,
+      error,
     } = this.props;
 
     // eslint-disable-next-line react/forbid-foreign-prop-types
     const [, inputCustom] = separateComponentProps(this.props, Checkbox.propTypes);
 
     return (
-      <div className={this.getRootStyle()}>
-        <Label htmlFor={this.id} className={this.getLabelStyle()}>
-          <input
-            id={this.id}
-            type="checkbox"
-            checked={checked}
-            {...inputCustom}
-            name={name}
-            className={css.checkboxInput}
-            onChange={this.handleChange}
-            onFocus={this.handleFocus}
-            onBlur={this.handleBlur}
-            disabled={disabled}
-            ref={(ref) => { this.input = ref; }}
-            autoFocus={autoFocus}
-            value={value}
-            aria-invalid={!!(this.props.error)}
-            required={required}
-          />
-          <span className={css.labelCheck}>
-            <svg height="10" width="10" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 14 14">
-              <path
-                fill="none"
-                strokeWidth="1.5"
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                strokeMiterlimit="10"
-                d="M10.395 4.617L5.63 9.383 3.605 7.358"
-              />
-            </svg>
+      <div className={this.getRootClasses()}>
+        <Label
+          tagName={label ? 'label' : 'span'}
+          htmlFor={label ? this.id : undefined}
+          className={this.getLabelClasses()}
+        >
+          { (vertical && label) && this.renderLabelText() }
+          <span className={this.getInnerClasses()}>
+            <input
+              id={this.id}
+              type="checkbox"
+              checked={checked}
+              {...inputCustom}
+              name={name}
+              className={css.input}
+              onChange={this.handleChange}
+              onFocus={this.handleFocus}
+              onBlur={this.handleBlur}
+              disabled={disabled}
+              ref={this.input}
+              autoFocus={autoFocus}
+              value={value}
+              aria-invalid={!!error}
+              required={required}
+            />
+            <span className={css.checkboxIcon}>
+              <svg height="10" width="10" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 14 14">
+                <path
+                  fill="none"
+                  strokeWidth="1.5"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeMiterlimit="10"
+                  d="M10.395 4.617L5.63 9.383 3.605 7.358"
+                />
+              </svg>
+            </span>
+            { (!vertical && (label || readOnly)) && this.renderLabelText() }
           </span>
-          { (label || readOnly) &&
-            (
-              <span className={css.labelText}>
-                { label }
-                { required && <Asterisk /> }
-                { readOnly && (
-                  <Icon size="small" icon="lock">
-                    <span className="sr-only">
-                      <FormattedMessage id="stripes-components.readonly" />
-                    </span>
-                  </Icon>
-                ) }
-              </span>
-            )
-          }
         </Label>
         <div role="alert">
-          {this.getFeedbackElement()}
+          {this.renderFeedbackElement()}
         </div>
       </div>
     );
diff --git a/lib/Checkbox/readme.md b/lib/Checkbox/readme.md
index 014062a3b..8eb4cc8c8 100644
--- a/lib/Checkbox/readme.md
+++ b/lib/Checkbox/readme.md
@@ -1,2 +1,73 @@
 # Checkbox
-More information coming soon..
\ No newline at end of file
+Renders a basic HTML checkbox.
+
+## Usage
+```js
+<Checkbox
+  label="My Checkbox"
+  checked={true}
+  value="bananas"
+  onChange={(event) => {
+    // consume event.target.value
+  }}
+/>
+```
+
+## Usage with external label
+The Checkbox component automatically renders a `<label>` when a `label`-prop is present but it is also possible to render it with an external label – as long as you provide a `htmlFor`-attribute for the label that matches the ID of the `<Checkbox>`.
+
+```js
+  import { Checkbox, Label } from '@folio/stripes/components';
+
+  <fieldset>
+    <Label for="my-external-label">My external label</Label>
+    <Checkbox id="my-external-label" inline />
+  </fieldset>
+```
+
+## Properties
+
+Name | type | description | default
+--- | --- | --- | ---
+autoFocus | bool | If this prop is `true`, will automatically focus on mount | `false`
+checked | bool | Marks the checkbox as checked (true) or unchecked (false) | `false`
+className | string | Adds a custom class on the root element | `undefined`
+disabled | bool | Sets the checkbox as disabled | `false`
+error | string, node | Renders an error message below the checkbox | `undefined`
+fullWidth | bool | Styles input to a width of 100% of its container | `false`
+id | string | HTML id attribute applied to input - will also set the HtmlFor attribute of the `<label>`-element if a label-prop is set | autogenerated
+inline | bool | Renders the checkbox inline | `false`
+innerClass | string | Adds a custom class name for the inner element of the component | `undefined`
+inputRef | object or func | Supplies a ref to the rendered `<input>` | `undefined`
+label | string | Renders a label for the checkbox | `undefined`
+labelClass | string | Adds a custom class name on the `<label>`-element | `undefined`
+name | string | Sets the name of the input | `undefined`
+onBlur | func | Event handler for the input's `onBlur` event | `undefined`
+onChange | func | Event handler for the input's `onChange` event | `undefined`
+onFocus | func | Event handler for the input's `onFocus` event | `undefined`
+readOnly | bool | Renders the field as "read only" | `false`
+required | bool | Sets the field as required | `false`
+value | string | Sets the selected value for the input | `undefined`
+vertical | bool | Renders the label vertically (above the checkbox) | `false`
+warning | string, node | Renders a warning message below the checkbox | `undefined`
+
+
+## Use with React Final Form
+```js
+  import { Field } from 'react-final-form';
+  import { Checkbox } from '@folio/stripes/components';
+
+  <Field
+    component={Checkbox}
+    label="green"
+    name="bananas"
+    value="green"
+  />
+
+  <Field
+    component={Checkbox}
+    label="ripe"
+    name="bananas"
+    value="ripe"
+  />
+```
\ No newline at end of file
diff --git a/lib/Checkbox/stories/BasicUsage.js b/lib/Checkbox/stories/BasicUsage.js
index dffb0bbfa..18cefb88b 100644
--- a/lib/Checkbox/stories/BasicUsage.js
+++ b/lib/Checkbox/stories/BasicUsage.js
@@ -5,103 +5,94 @@
 import React from 'react';
 import Checkbox from '../Checkbox';
 import Label from '../../Label';
+import Headline from '../../Headline';
 
-export default class CheckboxExample extends React.Component {
-  constructor() {
-    super();
-    this.state = {
-      checked: ['checkbox_4'],
-    };
-  }
+const CheckboxExample = () => (
+  <div>
+    <Checkbox
+      label="Checkbox with label (full width)"
+    />
+    <br />
+    <Checkbox
+      label="Inline Checkbox with label (disabled)"
+      inline
+      disabled
+    />
+    <br />
+    <br />
+    <Checkbox
+      label="Inline Checkbox with label (read only)"
+      checked
+      inline
+      readOnly
+    />
+    <br />
+    <br />
+    <Checkbox
+      label="Required checkbox"
+      inline
+      required
+    />
+    <br />
+    <br />
+    <hr />
+    <br />
+    <Headline size="large">No label</Headline>
+    <Checkbox
+      aria-label="My label"
+      inline
+    />
+    <br />
+    <br />
+    <Label htmlFor="external-label">Checkbox with external label</Label>
+    <Checkbox id="external-label" name="external-label" inline />
+    <br />
+    <br />
+    <hr />
+    <br />
+    <Headline size="large">Vertical label</Headline>
+    <Checkbox
+      vertical
+      label="My label"
+    />
+    <br />
+    <br />
+    <hr />
+    <br />
+    <Headline size="large">Inline</Headline>
+    <Checkbox
+      label="Inline Checkbox with label"
+      inline
+    />
+    <br />
+    <br />
+    <Label>Stacked inline checkboxes</Label>
+    <Checkbox label="JavaScript" inline />
+    <Checkbox label="PHP" inline />
+    <Checkbox label="C++" inline />
+    <Checkbox label="ASP.net" inline />
+    <br />
+    <br />
+    <hr />
+    <br />
+    <Headline size="large">With error</Headline>
+    <Checkbox
+      label="Checkbox with error"
+      error="This field is required"
+      required
+    />
+    <br />
+    <hr />
+    <br />
+    <Headline size="large">With warning</Headline>
+    <Checkbox
+      label="Checkbox with warning"
+      warning="This is a warning"
+      required
+    />
+    <br />
+    <br />
+  </div>
+);
 
-  onChange = e => {
-    const { checked } = this.state;
-    const { value } = e.target;
-    const newChecked = checked.indexOf(value) >= 0 ?
-      checked.filter(val => val !== value) :
-      [...checked, value];
-
-    this.setState({
-      checked: newChecked,
-    });
-  }
-
-  isChecked = (val) => {
-    return this.state.checked.indexOf(val) >= 0;
-  }
-
-  render() {
-    return (
-      <div>
-        <Checkbox
-          name="checkbox"
-          label="Checkbox with label (full width)"
-          onChange={this.onChange}
-          value="checkbox_1"
-          checked={this.isChecked('checkbox_1')}
-        />
-        <br aria-hidden="true" />
-        <Checkbox
-          name="checkbox"
-          label="Inline Checkbox with label"
-          onChange={this.onChange}
-          value="checkbox_2"
-          checked={this.isChecked('checkbox_2')}
-          inline
-        />
-        <br aria-hidden="true" />
-        <br aria-hidden="true" />
-        <Checkbox
-          name="checkbox"
-          label="Inline Checkbox with label (disabled)"
-          onChange={this.onChange}
-          value="checkbox_3"
-          checked={this.isChecked('checkbox_3')}
-          inline
-          disabled
-        />
-        <br aria-hidden="true" />
-        <br aria-hidden="true" />
-        <Checkbox
-          name="checkbox"
-          label="Inline Checkbox with label (read only)"
-          onChange={this.onChange}
-          value="checkbox_4"
-          checked={this.isChecked('checkbox_4')}
-          inline
-          readOnly
-        />
-        <br aria-hidden="true" />
-        <br aria-hidden="true" />
-        <Checkbox
-          name="checkbox"
-          label="Required checkbox"
-          onChange={this.onChange}
-          value="checkbox_5"
-          checked={this.isChecked('checkbox_5')}
-          inline
-          required
-        />
-        <br aria-hidden="true" />
-        <br aria-hidden="true" />
-        This is an
-        <Checkbox
-          name="checkbox"
-          onChange={this.onChange}
-          value="checkbox_6"
-          checked={this.isChecked('checkbox_6')}
-          inline
-        />
-        {' '}
-inline checkbox with no label.
-        <br aria-hidden="true" />
-        <br aria-hidden="true" />
-        <Label>Stacked inline checkboxes</Label>
-        <Checkbox label="JavaScript" inline />
-        <Checkbox label="PHP" inline />
-        <Checkbox label="C++" inline />
-        <Checkbox label="ASP.net" inline />
-      </div>
-    );
-  }
-}
+export default CheckboxExample;
diff --git a/lib/Checkbox/tests/Checkbox-test.js b/lib/Checkbox/tests/Checkbox-test.js
index 5cace361a..e73b209cd 100644
--- a/lib/Checkbox/tests/Checkbox-test.js
+++ b/lib/Checkbox/tests/Checkbox-test.js
@@ -5,6 +5,7 @@ import { expect } from 'chai';
 import { Field } from 'redux-form';
 import { mount, mountWithContext } from '../../../tests/helpers';
 import TestForm from '../../../tests/TestForm';
+import Harness from '../../../tests/Harness';
 
 import Checkbox from '../Checkbox';
 import CheckboxInteractor from './interactor';
@@ -12,16 +13,50 @@ import CheckboxInteractor from './interactor';
 describe('Checkbox', () => {
   const checkbox = new CheckboxInteractor();
 
-  describe('with an id', () => {
+  describe('render a checkbox', () => {
+    let focused;
     beforeEach(async () => {
       await mount(
-        <Checkbox id="checkbox-test" />
+        <Checkbox
+          id="checkbox-test"
+          className="custom-class"
+          label="My label"
+          aria-label="My aria label"
+          onFocus={() => { focused = true; }}
+          fullWidth
+          vertical
+        />
       );
+      await checkbox.focusInput();
     });
 
     it('has an id on the input element', () => {
       expect(checkbox.id).to.equal('checkbox-test');
     });
+
+    it('has a custom className applied', () => {
+      expect(checkbox.className).to.include('custom-class');
+    });
+
+    it('is full width', () => {
+      expect(checkbox.isFullWidth).to.be.true;
+    });
+
+    it('is has a label', () => {
+      expect(checkbox.label).to.equal('My label');
+    });
+
+    it('is rendered vertically', () => {
+      expect(checkbox.isVertical).to.be.true;
+    });
+
+    it('is has an aria-label', () => {
+      expect(checkbox.ariaLabel).to.equal('My aria label');
+    });
+
+    it('should fire an onFocus callback', () => {
+      expect(focused).to.be.true;
+    });
   });
 
   describe('with warning text', () => {
@@ -54,6 +89,10 @@ describe('Checkbox', () => {
     it('applies an error class', () => {
       expect(checkbox.hasErrorStyle).to.be.true;
     });
+
+    it('sets the aria-invalid attribute to true', () => {
+      expect(checkbox.ariaInvalid).to.equal('true');
+    });
   });
 
   describe('with a value', () => {
@@ -63,6 +102,7 @@ describe('Checkbox', () => {
       await mount(
         <Checkbox
           value="bananas"
+          label="My label"
           onChange={(event) => { output = event.target.value; }}
         />
       );
@@ -95,6 +135,7 @@ describe('Checkbox', () => {
         <TestForm>
           <Field
             name="bananas"
+            label="Bananas"
             component={Checkbox}
             onChange={(event, newValue) => {
               output = newValue;
@@ -137,4 +178,80 @@ describe('Checkbox', () => {
       });
     });
   });
+
+  describe('if a createRef() is passed to the inputRef-prop', () => {
+    const ref = React.createRef();
+
+    beforeEach(async () => {
+      await mount(
+        <Checkbox
+          id="checkbox-ref-test"
+          inputRef={ref}
+        />
+      );
+    });
+
+    it('should return a valid ref', () => {
+      expect(ref.current).to.not.be.null;
+    });
+  });
+
+  describe('if a function is passed to the inputRef-prop', () => {
+    let element;
+
+    beforeEach(async () => {
+      await mount(
+        <Checkbox inputRef={(el) => { element = el; }} />
+      );
+    });
+
+    it('should pass a HTML input element as a parameter to the passed function', () => {
+      expect(element.constructor.name).to.equal('HTMLInputElement');
+    });
+  });
+
+  describe('if the readOnly prop is true', () => {
+    let changed;
+
+    beforeEach(async () => {
+      await mount(
+        <Harness>
+          <Checkbox
+            label="Read only checkbox"
+            id="checkbox-ref-test"
+            readOnly
+            onChange={() => { changed = true; }}
+          />
+        </Harness>
+      );
+
+      await checkbox.clickLabel();
+    });
+
+    it('should not fire the onChange callback', () => {
+      expect(changed).to.be.undefined;
+    });
+  });
+
+  describe('a checkbox without a label-prop', () => {
+    let output;
+    beforeEach(async () => {
+      await mount(
+        <Checkbox
+          id="checkbox-no-label-test"
+          value="no-label-checkbox"
+          onChange={(event) => { output = event.target.value; }}
+        />
+      );
+      await checkbox.clickInput();
+    });
+
+    it('should not render a <label>-element', () => {
+      expect(checkbox.hasLabelElement).to.be.false;
+    });
+
+    it('should fire onChange callback when clicking the <input>', () => {
+      expect(output).to.equal('no-label-checkbox');
+    });
+  });
 });
diff --git a/lib/Checkbox/tests/interactor.js b/lib/Checkbox/tests/interactor.js
index 9b4f0df52..d86df1b3e 100644
--- a/lib/Checkbox/tests/interactor.js
+++ b/lib/Checkbox/tests/interactor.js
@@ -7,20 +7,30 @@ import {
   property,
   text,
   value,
+  isPresent,
+  focusable,
 } from '@bigtest/interactor';
 import styles from '../Checkbox.css';
 
-const rootClass = `.${styles.checkbox}`;
-
 export default interactor(class CheckboxInteractor {
+  static defaultScope = `.${styles.checkbox}`;
+  className = attribute('class');
   id = attribute('input', 'id');
   clickLabel = clickable('label');
+  clickInput = clickable('input');
   blurInput = blurrable('input');
+  focusInput = focusable('input');
   inputValue = value('input');
   isChecked = property('input', 'checked');
+  label = text(`.${styles.label}`);
+  hasLabelElement = isPresent('label');
   feedbackText = text(`.${styles.checkboxFeedback}`);
-  hasWarningStyle = hasClass(rootClass, styles.hasWarning);
-  hasErrorStyle = hasClass(rootClass, styles.hasError);
+  hasWarningStyle = hasClass(styles.hasWarning);
+  hasErrorStyle = hasClass(styles.hasError);
+  isFullWidth = hasClass(styles.fullWidth);
+  isVertical = hasClass(styles.vertical);
+  ariaInvalid = attribute('input', 'aria-invalid');
+  ariaLabel = attribute('input', 'aria-label');
 
   clickAndBlur() {
     return this
diff --git a/lib/FilterGroups/FilterGroups.css b/lib/FilterGroups/FilterGroups.css
index 730c58bae..8bae28d8d 100644
--- a/lib/FilterGroups/FilterGroups.css
+++ b/lib/FilterGroups/FilterGroups.css
@@ -2,14 +2,11 @@
  * Filter Groups
 */
 
-.filterGroupLabelInteractionStyles {
-  composes: boxOffsetStartMedium hasDot focusDotPositionStart from "../sharedStyles/interactionStyles.css";
-}
-
-label.filterGroupLabel {
+.filterGroupLabel {
   padding: 0 0 0 1.3em;
+  composes: boxOffsetStartMedium hasDot focusDotPositionStart from "../sharedStyles/interactionStyles.css";
 }
 
-[dir="rtl"] label.filterGroupLabel {
+[dir="rtl"] .filterGroupLabel {
   padding: 0 1.3em 0 0;
 }
diff --git a/lib/FilterGroups/FilterGroups.js b/lib/FilterGroups/FilterGroups.js
index 4ae9283cb..8dd210a22 100644
--- a/lib/FilterGroups/FilterGroups.js
+++ b/lib/FilterGroups/FilterGroups.js
@@ -22,8 +22,7 @@ const FilterCheckbox = (props) => {
     name={fullName}
     checked={checked}
     onChange={ocf}
-    marginBottom0
-    labelClass={`${css.filterGroupLabel} ${css.filterGroupLabelInteractionStyles}`}
+    innerClass={css.filterGroupLabel}
     fullWidth
     disabled={disabled}
   />);
diff --git a/lib/Label/Label.css b/lib/Label/Label.css
index 987f2e1a3..481f5b873 100644
--- a/lib/Label/Label.css
+++ b/lib/Label/Label.css
@@ -9,6 +9,6 @@
   align-items: center;
   font-size: var(--font-size-medium);
   line-height: var(--line-height);
-  margin-bottom: 0.25rem;
+  margin-bottom: var(--control-label-margin-bottom);
   color: var(--color-text);
 }
diff --git a/lib/global.css b/lib/global.css
index 3800e4808..e32c28961 100644
--- a/lib/global.css
+++ b/lib/global.css
@@ -151,6 +151,8 @@ button {
   white-space: nowrap;
   clip-path: inset(50%);
   border: 0;
+  height: 0;
+  width: 0;
 }
 
 :global(.tether-element) {
diff --git a/lib/variables.css b/lib/variables.css
index 5672133cc..ec477e9af 100644
--- a/lib/variables.css
+++ b/lib/variables.css
@@ -21,11 +21,12 @@
   --secondary: #999;
   --error: #900;
   --danger: #900;
-  --warn: #e27c3e;
+  --warn: #943e00;
   --success: #070;
   --control-margin-bottom: 1rem;
   --control-min-size-touch: 44px;
   --control-min-size-desktop: 24px;
+  --control-label-margin-bottom: 0.25rem;
   --radius: 6px;
   --gutter: 1rem;
   --gutter-static: 15px;