Implement help text for TextField, TextArea, SearchField, and Picker (#1846)

* Update useControlledState for StrictMode
The current useControlledState has side effects, this causes an issue StrictMode

* remove out of date comment

* Add help text interfaces

Adapted from GH issue description

* Basic setup for useField

* Add HelpText to Field when description or errorMessage exist

* Start adding desc/err msg to TextField and Combobox

* Fix render and aria-describedby logic

* More improvements to rendering logic

* Only return props for desc/errMsg if they're passed in

* Refactor TextFieldBase to use Field

* Preserve aria-describedby prop

* Remove useField.mdx placeholder doc

* Props syntax refactor

* Linting and type fixes

* Create HelpText stories and chromatic

Also rearrange order of aria-describedby elements. Move props['aria-describedby'] from beginning to end, so AT announces help text description first, which makes more sense.

* Add Textfield stories

* Add styles

Used the spectrum-css helptext component styles for reference. https://github.com/adobe/spectrum-css/blob/main/components/vars/css/components/spectrum-helptext.css

* Update styles with latest from spectrum-css and support showIcon

Updated spectrum-css helptext component: https://github.com/adobe/spectrum-css/tree/DNA-7.0-beta/components/helptext

* Support fields with no visible label

Refactored return logic in TextFieldBase: always return a `<Field>` and delegate rendering a simple `React.cloneElement` to Field.tsx.

In Field.tsx, only return a simple `React.cloneElement` if both a label and help text are missing. Otherwise, conditionally render a `<Label>` and `<HelpText>`.

* Make 'description and error message' story interactive

* Pass temp Field props in SearchWithin to fix lint

* Fix field styles when labelPosition: side

Form field and help text components (but not label) are wrapped in a vertical flex container, so that the help text renders below the field while the label is to the side. This flex container shouldn't render when no help text is provided.

Modified CSS so that this new wrapper's width defaults to the default form field width, but still respects a user override.

* Remove unused styleProps reference from TextFieldBase

These styleProps are now always processed in `<Field>`. Follow up fix to a4d479a.

* Support labelAlign=end

* Add help text to Form stories and fix labelPosition=side styles

* Remove unused style

* Remove 2nd margin between icon and help text when labelAlign=end

* Add more chromatic stories

* Refactor labelAlign=side style

* Add help text to MobileComboBox

* Add help text to Picker

* WIP: Add help text to CheckboxGroup

Pushing for visibility in the PR and then reverting.

Outstanding questions and issues:
- Adds .spectrum-Field-field to role="presentation" div: good or bad?
- Should help text live outside of role="group"?
- Workaround of hardcoding wrapper width to `--spectrum-field-default-width` breaks CheckboxGroup since normally its width expands/shrinks to fit longest checkbox label

* Revert "WIP: Add help text to CheckboxGroup"

This reverts commit 1bc5a73.

* Temporarily remove help text from Combobox

Will bring it back once we find a workaround for hardcoding `.spectrum-Field-wrapper` width to 192px.

Note that there's a bug in prod where comboboxes with `.spectrum-Field--positionTop` are already hardcoded to 192px width instead of 224px to account for the button.

* Make descriptionProps, errorMessageProps opt. on SpectrumFieldProps

Not every component that uses <Field> supports help text.

* Add help text to SearchField and TextArea

* PR comments: Add doc comment block & validationState=valid story

* PR comments: rename showIcon to showErrorIcon

* Skip failing NumberField test

This is related to some breaking behavior for controlled components that use Field. Need more investigation on why calling `useSlotId()` in `useField.ts` interferes with `useControlledState`.

* Don't let form fields accept showErrorIcon prop

Make SpectrumTextFieldProps and SpectrumPickerProps extend from HelpTextProps instead of SpectrumHelpTextProps. Now only HelpText and Field can accept `showErrorIcon`.

When CheckboxGroup and RadioGroup are supported, they'll set it to true while all other components that use Field should set it to false. I'll also add back tests that verify the icon shows.

* Remove useField from monorepo for now

Co-authored-by: Rob Snow <[email protected]>
Co-authored-by: Dylan Kario <[email protected]>

Author: 3 people

packages/@adobe/spectrum-css-temp/components/fieldlabel/index.css

@@ -58,7 +58,7 @@ governing permissions and limitations under the License.
   text-align: end; /* labelPosition=side case */
 }
 
-/* A Field is a wrapper for a FieldLabel and a field component (e.g. textfield).
+/* A Field is a wrapper for a FieldLabel, a field component (e.g. textfield), and a HelpText.
  * By default, labels are placed above the field. Fields have a default width, and the
  * label will wrap within this width. The width of the whole field can be overridden by the user,
  * and this causes both the label and inner field to resize as well. */
@@ -86,10 +86,25 @@ governing permissions and limitations under the License.
     display: inline-flex;
     align-items: flex-start;
 
-    .spectrum-Field-field {
+    /* Wraps the field & help text, but not the label */
+    .spectrum-Field-wrapper {
       flex: 1;
       /* Setting `flex: 1;` is equivalent to `flex: 1 1 0;`, which means we expect to be able to shrink
-      * To be able to shrink, we must have a min-width that isn't 'auto' */
+       * To be able to shrink, we must have a min-width that isn't 'auto' */
+      min-width: 0;
+      /* TODO: By default, vertical flex wrapper for `labelPosition: side` should have default field width.
+       * This is a workaround until we find a better way to set the width of the field & help text.
+       * Should default to form field's default width and and allow users to override with custom width. */
+      width: var(--spectrum-field-default-width);
+
+      .spectrum-Field-field {
+        /* If the user overrides the width of the field, propagate to the inner component */
+        width: 100%;
+      }
+    }
+
+    .spectrum-Field-field {
+      flex: 1;
       min-width: 0;
     }
 
@@ -122,6 +137,10 @@ governing permissions and limitations under the License.
       display: table-cell;
     }
 
+    .spectrum-Field-wrapper {
+      width: 100%;
+    }
+
     .spectrum-Field-field {
       display: table-cell;
       width: auto;

packages/@adobe/spectrum-css-temp/components/helptext/index.css

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2021 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+@import '../commons/index.css';
+
+:root {
+  --spectrum-helptext-neutral-texticon-text-size: var(--spectrum-global-dimension-font-size-75);
+  --spectrum-helptext-neutral-texticon-icon-gap: var(--spectrum-global-dimension-size-100);
+
+  --spectrum-helptext-negative-texticon-icon-padding-top: var(--spectrum-global-dimension-size-40);
+  --spectrum-helptext-negative-texticon-icon-padding-bottom: var(--spectrum-global-dimension-size-40);
+
+  --spectrum-helptext-neutral-textonly-text-padding-top: var(--spectrum-global-dimension-static-size-50);
+  --spectrum-helptext-neutral-textonly-text-transform: none;
+  --spectrum-helptext-neutral-textonly-text-letter-spacing: var(--spectrum-global-font-letter-spacing-none);
+
+  /* Uses value for DNA variable --spectrum-helptext-l-neutral-textonly-text-padding-bottom, since m variant doesn't exist */
+  --spectrum-helptext-neutral-textonly-text-padding-bottom: var(--spectrum-global-dimension-size-115);
+  /* Override: DNA uses --spectrum-alias-component-text-line-height */
+  --spectrum-helptext-neutral-textonly-text-line-height: var(--spectrum-global-font-line-height-small);
+}
+
+.spectrum-HelpText {
+  display: flex;
+  font-size: var(--spectrum-helptext-neutral-texticon-text-size);
+  .spectrum-HelpText-validationIcon {
+    margin-inline-end: var(--spectrum-helptext-neutral-texticon-icon-gap);
+    padding-block: var(--spectrum-helptext-negative-texticon-icon-padding-top) var(--spectrum-helptext-negative-texticon-icon-padding-bottom);
+    flex-shrink: 0;
+  }
+  .spectrum-HelpText-text {
+    /* Not in DNA: make text fill up all horizontal space. */
+    flex: 1;
+
+    margin-inline-end: var(--spectrum-helptext-neutral-texticon-icon-gap);
+    padding-block: var(--spectrum-helptext-neutral-textonly-text-padding-top) var(--spectrum-helptext-neutral-textonly-text-padding-bottom);
+    line-height: var(--spectrum-helptext-neutral-textonly-text-line-height);
+    text-transform: var(--spectrum-helptext-neutral-textonly-text-transform);
+    letter-spacing: var(--spectrum-helptext-neutral-textonly-text-letter-spacing);
+  }
+  /* Not in DNA */
+  &.spectrum-HelpText--alignEnd {
+    text-align: end; /* Works with labelPosition=top and labelPosition=side */
+    .spectrum-HelpText-text {
+      margin-inline-end: 0;
+      margin-inline-start: var(--spectrum-helptext-neutral-texticon-icon-gap);
+    }
+    .spectrum-HelpText-validationIcon {
+      margin-inline-end: 0;
+    }
+  }
+}

packages/@adobe/spectrum-css-temp/components/helptext/skin.css

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2021 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+:root {
+  --spectrum-helptext-neutral-texticon-text-color: var(--spectrum-alias-label-text-color);
+  --spectrum-helptext-neutral-texticon-text-color-disabled: var(--spectrum-alias-text-color-disabled);
+
+  /* Override: DNA uses --spectrum-semantic-negative-text-color-small */
+  --spectrum-helptext-negative-texticon-text-color: var(--spectrum-semantic-negative-color-text-small);
+  /* Override: DNA uses --spectrum-semantic-negative-icon-color */
+  --spectrum-helptext-negative-texticon-icon-color: var(--spectrum-semantic-negative-color-text-small);
+}
+
+.spectrum-HelpText--neutral {
+  .spectrum-HelpText-text {
+    color: var(--spectrum-helptext-neutral-texticon-text-color);
+  }
+  &.is-disabled {
+    .spectrum-HelpText-text {
+      color: var(--spectrum-helptext-neutral-texticon-text-color-disabled);
+    }
+  }
+}
+
+.spectrum-HelpText--negative {
+  .spectrum-HelpText-validationIcon {
+    color: var(--spectrum-helptext-negative-texticon-icon-color);
+  }
+  .spectrum-HelpText-text {
+    color: var(--spectrum-helptext-negative-texticon-text-color);
+  }
+}

packages/@adobe/spectrum-css-temp/components/helptext/vars.css

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2021 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+@import './index.css';
+@import './skin.css';

packages/@react-aria/combobox/src/useComboBox.ts

@@ -48,7 +48,11 @@ interface ComboBoxAria<T> {
   /** Props for the list box, to be passed to [useListBox](useListBox.html). */
   listBoxProps: AriaListBoxOptions<T>,
   /** Props for the optional trigger button, to be passed to [useButton](useButton.html). */
-  buttonProps: AriaButtonProps
+  buttonProps: AriaButtonProps,
+  /** Props for the combo box description element, if any. */
+  descriptionProps: HTMLAttributes<HTMLElement>,
+  /** Props for the combo box error message element, if any. */
+  errorMessageProps: HTMLAttributes<HTMLElement>
 }
 
 /**
@@ -152,7 +156,7 @@ export function useComboBox<T>(props: AriaComboBoxProps<T>, state: ComboBoxState
     state.setFocused(true);
   };
 
-  let {labelProps, inputProps} = useTextField({
+  let {labelProps, inputProps, descriptionProps, errorMessageProps} = useTextField({
     ...props,
     onChange: state.setInputValue,
     onKeyDown: !isReadOnly && chain(state.isOpen && collectionProps.onKeyDown, onKeyDown),
@@ -316,6 +320,8 @@ export function useComboBox<T>(props: AriaComboBoxProps<T>, state: ComboBoxState
       shouldUseVirtualFocus: true,
       shouldSelectOnPressUp: true,
       shouldFocusOnHover: true
-    })
+    }),
+    descriptionProps,
+    errorMessageProps
   };
 }

packages/@react-aria/label/src/index.ts

@@ -10,4 +10,5 @@
  * governing permissions and limitations under the License.
  */
 
+export * from './useField';
 export * from './useLabel';

packages/@react-aria/label/src/useField.ts

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2021 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {HelpTextProps} from '@react-types/shared';
+import {HTMLAttributes} from 'react';
+import {LabelAria, LabelAriaProps, useLabel} from './useLabel';
+import {mergeProps, useSlotId} from '@react-aria/utils';
+
+interface AriaFieldProps extends LabelAriaProps, HelpTextProps {}
+
+export interface FieldAria extends LabelAria {
+  /** Props for the description element, if any. */
+  descriptionProps: HTMLAttributes<HTMLElement>,
+  /** Props for the error message element, if any. */
+  errorMessageProps: HTMLAttributes<HTMLElement>
+}
+
+/**
+ * Provides the accessibility implementation for input fields.
+ * Fields accept user input, gain context from their label, and may display a description or error message.
+ * @param props - Props for the Field.
+ */
+export function useField(props: AriaFieldProps): FieldAria {
+  let {description, errorMessage} = props;
+  let {labelProps, fieldProps} = useLabel(props);
+
+  let descriptionId = useSlotId();
+  let errorMessageId = useSlotId();
+
+  fieldProps = mergeProps(fieldProps, {
+    'aria-describedby': [
+      descriptionId,
+      // Use aria-describedby for error message because aria-errormessage is unsupported using VoiceOver or NVDA. See https://github.com/adobe/react-spectrum/issues/1346#issuecomment-740136268
+      errorMessageId,
+      props['aria-describedby']
+    ].filter(Boolean).join(' ') || undefined
+  });
+
+  let descriptionProps: HTMLAttributes<HTMLElement> = {};
+  let errorMessageProps: HTMLAttributes<HTMLElement> = {};
+  if (description) {
+    descriptionProps.id = descriptionId;
+  }
+  if (errorMessage) {
+    errorMessageProps.id = errorMessageId;
+  }
+
+  return {
+    labelProps,
+    fieldProps,
+    descriptionProps,
+    errorMessageProps
+  };
+}

packages/@react-aria/label/src/useLabel.ts

@@ -14,15 +14,15 @@ import {AriaLabelingProps, DOMProps, LabelableProps} from '@react-types/shared';
 import {ElementType, LabelHTMLAttributes} from 'react';
 import {useId, useLabels} from '@react-aria/utils';
 
-interface LabelAriaProps extends LabelableProps, DOMProps, AriaLabelingProps {
+export interface LabelAriaProps extends LabelableProps, DOMProps, AriaLabelingProps {
   /**
    * The HTML element used to render the label, e.g. 'label', or 'span'.
    * @default 'label'
    */
   labelElementType?: ElementType
 }
 
-interface LabelAria {
+export interface LabelAria {
   /** Props to apply to the label container element. */
   labelProps: LabelHTMLAttributes<HTMLLabelElement>,
   /** Props to apply to the field container element being labeled. */

packages/@react-aria/label/test/useField.test.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {renderHook} from '@testing-library/react-hooks';
+import {useField} from '../';
+
+describe('useField', function () {
+  let renderFieldHook = (fieldProps) => {
+    let {result} = renderHook(() => useField(fieldProps));
+    return result.current;
+  };
+
+  it('should return label props', function () {
+    let {labelProps, fieldProps} = renderFieldHook({label: 'Test'});
+    expect(labelProps.id).toBeDefined();
+    expect(fieldProps.id).toBeDefined();
+  });
+
+  it('should return props for description and error message if they are passed in', function () {
+    let {descriptionProps, errorMessageProps} = renderFieldHook({label: 'Test', description: 'Description', errorMessage: 'Error'});
+    expect(descriptionProps.id).toBeDefined();
+    expect(errorMessageProps.id).toBeDefined();
+  });
+
+  it('should not return props for description and error message if they are not passed in', function () {
+    let {descriptionProps, errorMessageProps} = renderFieldHook({label: 'Test'});
+    expect(descriptionProps).toEqual({});
+    expect(errorMessageProps).toEqual({});
+  });
+});

packages/@react-aria/searchfield/src/useSearchField.ts

@@ -12,7 +12,7 @@
 
 import {AriaButtonProps} from '@react-types/button';
 import {AriaSearchFieldProps} from '@react-types/searchfield';
-import {InputHTMLAttributes, LabelHTMLAttributes, RefObject} from 'react';
+import {HTMLAttributes, InputHTMLAttributes, LabelHTMLAttributes, RefObject} from 'react';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
 import {SearchFieldState} from '@react-stately/searchfield';
@@ -25,7 +25,11 @@ interface SearchFieldAria {
   /** Props for the input element. */
   inputProps: InputHTMLAttributes<HTMLInputElement | HTMLTextAreaElement>,
   /** Props for the clear button. */
-  clearButtonProps: AriaButtonProps
+  clearButtonProps: AriaButtonProps,
+  /** Props for the description element. */
+  descriptionProps: HTMLAttributes<HTMLElement>,
+  /** Props for the error message element. */
+  errorMessageProps: HTMLAttributes<HTMLElement>
 }
 
 /**
@@ -84,7 +88,7 @@ export function useSearchField(
     inputRef.current.focus();
   };
 
-  let {labelProps, inputProps} = useTextField({
+  let {labelProps, inputProps, descriptionProps, errorMessageProps} = useTextField({
     ...props,
     value: state.value,
     onChange: state.setValue,
@@ -106,6 +110,8 @@ export function useSearchField(
       preventFocusOnPress: true,
       onPress: onClearButtonClick,
       onPressStart
-    }
+    },
+    descriptionProps,
+    errorMessageProps
   };
 }