EuiDescribedFormGroup component

CHANGELOG.md

@@ -5,6 +5,8 @@
 - Added `EuiEmptyPrompt` which can be used as a placeholder over empty tables and lists ([#711](https://github.com/elastic/eui/pull/711))
 - Added `EuiTabbedContent` ([#737](https://github.com/elastic/eui/pull/737))
 - `EuiComboBox` added buttons for clearing and opening/closing the combo box.  ([#698](https://github.com/elastic/eui/pull/698))
+- Added `EuiDescribedFormGroup` component, a wrapper around `EuiFormRow`(s) ([#707](https://github.com/elastic/eui/pull/707))
+- Added `describedByIds` prop to `EuiFormRow` to help with accessibility ([#707](https://github.com/elastic/eui/pull/707))
 
 **Bug fixes**
 

src-docs/src/views/form_layouts/described_form_group.js

@@ -0,0 +1,175 @@
+import React, {
+  Component,
+} from 'react';
+
+import {
+  EuiButton,
+  EuiCode,
+  EuiFieldText,
+  EuiForm,
+  EuiFormRow,
+  EuiDescribedFormGroup,
+  EuiFilePicker,
+  EuiRange,
+  EuiSelect,
+  EuiSwitch,
+} from '../../../../src/components';
+
+import makeId from '../../../../src/components/form/form_row/make_id';
+
+export default class extends Component {
+  constructor(props) {
+    super(props);
+
+    const idPrefix = makeId();
+
+    this.state = {
+      isSwitchChecked: false,
+      checkboxes: [{
+        id: `${idPrefix}0`,
+        label: 'Option one',
+      }, {
+        id: `${idPrefix}1`,
+        label: 'Option two is checked by default',
+      }, {
+        id: `${idPrefix}2`,
+        label: 'Option three',
+      }],
+      checkboxIdToSelectedMap: {
+        [`${idPrefix}1`]: true,
+      },
+      radios: [{
+        id: `${idPrefix}4`,
+        label: 'Option one',
+      }, {
+        id: `${idPrefix}5`,
+        label: 'Option two is selected by default',
+      }, {
+        id: `${idPrefix}6`,
+        label: 'Option three',
+      }],
+      radioIdSelected: `${idPrefix}5`,
+    };
+  }
+
+  onSwitchChange = () => {
+    this.setState({
+      isSwitchChecked: !this.state.isSwitchChecked,
+    });
+  }
+
+  onCheckboxChange = optionId => {
+    const newCheckboxIdToSelectedMap = ({ ...this.state.checkboxIdToSelectedMap, ...{
+        [optionId]: !this.state.checkboxIdToSelectedMap[optionId],
+      } });
+
+    this.setState({
+      checkboxIdToSelectedMap: newCheckboxIdToSelectedMap,
+    });
+  }
+
+  onRadioChange = optionId => {
+    this.setState({
+      radioIdSelected: optionId,
+    });
+  }
+
+  render() {
+    return (
+      <EuiForm>
+        <EuiDescribedFormGroup
+          idAria="single-example-aria"
+          title={<h3>Single text field</h3>}
+          description={
+            <span>
+              When using this with a single form row where this text serves as the help text for the input,
+              it is a good idea to pass <EuiCode>idAria=&quot;someID&quot;</EuiCode> to the form group and pass
+              <EuiCode>describedByIds=&#123;[someID]&#125;</EuiCode> to its form row.
+            </span>
+          }
+        >
+          <EuiFormRow
+            label="Text field"
+            describedByIds={['single-example-aria']}
+          >
+            <EuiFieldText name="first" />
+          </EuiFormRow>
+        </EuiDescribedFormGroup>
+
+        <EuiDescribedFormGroup
+          title={<strong>Multiple fields</strong>}
+          titleSize="m"
+          description="Here are three form rows. The first form row does not have a title."
+        >
+          <EuiFormRow
+            hasEmptyLabelSpace
+            helpText={
+              <span>
+                We do not pass <EuiCode>describedByIds</EuiCode> when there are multiple form rows.
+              </span>
+            }
+          >
+            <EuiSelect
+              hasNoInitialSelection
+              options={[
+                { value: 'option_one', text: 'Option one' },
+                { value: 'option_two', text: 'Option two' },
+                { value: 'option_three', text: 'Option three' },
+              ]}
+            />
+          </EuiFormRow>
+
+          <EuiFormRow
+            label="File picker"
+          >
+            <EuiFilePicker />
+          </EuiFormRow>
+
+          <EuiFormRow
+            label="Range"
+          >
+            <EuiRange
+              min={0}
+              max={100}
+              name="range"
+              id="range"
+            />
+          </EuiFormRow>
+        </EuiDescribedFormGroup>
+
+        <EuiDescribedFormGroup
+          title={<h2>Full width</h2>}
+          titleSize="xxxs"
+          description={
+            <span>
+              By default, <EuiCode>EuiDescribedFormGroup</EuiCode> will be double the default width of form elements.
+              However, you can pass <EuiCode>fullWidth</EuiCode> prop to this, the individual field and row components
+              to expand to their container.
+            </span>
+          }
+          fullWidth
+        >
+          <EuiFormRow
+            label="Use a switch instead of a single checkbox"
+            fullWidth
+          >
+            <EuiSwitch
+              name="switch"
+              label="Should we do this?"
+              checked={this.state.isSwitchChecked}
+              onChange={this.onSwitchChange}
+            />
+          </EuiFormRow>
+
+          <EuiFormRow fullWidth>
+            <EuiFieldText name="second" fullWidth />
+          </EuiFormRow>
+        </EuiDescribedFormGroup>
+
+        <EuiButton type="submit" fill>
+          Save form
+        </EuiButton>
+      </EuiForm>
+    );
+  }
+}

src-docs/src/views/form_layouts/form_layouts_example.js

@@ -10,6 +10,7 @@ import {
   EuiCode,
   EuiForm,
   EuiFormRow,
+  EuiDescribedFormGroup,
   EuiCheckboxGroup,
   EuiFieldNumber,
   EuiFieldPassword,
@@ -28,6 +29,10 @@ import FormRows from './form_rows';
 const formRowsSource = require('!!raw-loader!./form_rows');
 const formRowsHtml = renderToHtml(FormRows);
 
+import DescribedFormGroup from './described_form_group';
+const describedFormGroupSource = require('!!raw-loader!./described_form_group');
+const describedFormGroupHtml = renderToHtml(DescribedFormGroup);
+
 import FullWidth from './full_width';
 const fullWidthSource = require('!!raw-loader!./full_width');
 const fullWidthHtml = renderToHtml(FullWidth);
@@ -81,6 +86,26 @@ export const FormLayoutsExample = {
       EuiTextArea,
     },
     demo: <FormRows />,
+  }, {
+    title: 'Described form groups',
+    source: [{
+      type: GuideSectionTypes.JS,
+      code: describedFormGroupSource,
+    }, {
+      type: GuideSectionTypes.HTML,
+      code: describedFormGroupHtml,
+    }],
+    text: (
+      <p>
+        Use <EuiCode>EuiDescribedFormGroup</EuiCode> component to associate multiple <EuiCode>EuiFormRow</EuiCode>s.
+        It can also simply be used with one <EuiCode>EuiFormRow</EuiCode> as a way to display help text (or additional
+        text) next to the field instead of below (on mobile, will revert to being stacked).
+      </p>
+    ),
+    props: {
+      EuiDescribedFormGroup,
+    },
+    demo: <DescribedFormGroup />,
   }, {
     title: 'Full-width',
     source: [{

src-docs/src/views/form_layouts/form_rows.js

@@ -118,7 +118,6 @@ export default class extends Component {
         >
           <EuiSwitch
             name="switch"
-
             label="Should we do this?"
             checked={this.state.isSwitchChecked}
             onChange={this.onSwitchChange}

src-docs/src/views/form_layouts/full_width.js

@@ -36,6 +36,7 @@ export default () => (
         fullWidth
       />
     </EuiFormRow>
+
     <EuiFormRow
       label="Often useful for text areas"
       fullWidth

src/components/form/_index.scss

@@ -2,6 +2,7 @@
 @import 'mixins';
 
 @import 'checkbox/index';
+@import 'described_form_group/index';
 @import 'field_number/index';
 @import 'field_password/index';
 @import 'field_search/index';