Add basic validation docs for hooks (#5375)

Author: devongovett

packages/@react-aria/checkbox/docs/useCheckboxGroup.mdx

@@ -54,7 +54,7 @@ checkbox groups that can be styled as needed.
 * Checkbox groups are exposed to assistive technology via ARIA
 * Each checkbox is built with a native HTML `<input>` element, which can be optionally visually
   hidden to allow custom styling
-* Full support for browser features like form autofill
+* Full support for browser features like form autofill and validation
 * Keyboard focus management and cross browser normalization
 * Group and checkbox labeling support for assistive technology
 
@@ -105,9 +105,9 @@ import {useCheckboxGroupState} from '@react-stately/checkbox';
 let CheckboxGroupContext = React.createContext(null);
 
 function CheckboxGroup(props) {
-  let {children, label, description, errorMessage} = props;
+  let {children, label, description} = props;
   let state = useCheckboxGroupState(props);
-  let {groupProps, labelProps, descriptionProps, errorMessageProps} = useCheckboxGroup(props, state);
+  let {groupProps, labelProps, descriptionProps, errorMessageProps, isInvalid, validationErrors} = useCheckboxGroup(props, state);
 
   return (
     <div {...groupProps}>
@@ -116,8 +116,8 @@ function CheckboxGroup(props) {
         {children}
       </CheckboxGroupContext.Provider>
       {description && <div {...descriptionProps} style={{fontSize: 12}}>{description}</div>}
-      {errorMessage && state.isInvalid &&
-        <div {...errorMessageProps} style={{color: 'red', fontSize: 12}}>{errorMessage}</div>
+      {isInvalid &&
+        <div {...errorMessageProps} style={{color: 'red', fontSize: 12}}>{validationErrors.join(' ')}</div>
       }
     </div>
   );
@@ -212,17 +212,46 @@ The `description` prop can be used to associate additional help text with a chec
 </CheckboxGroup>
 ```
 
-### Error message
+### Group validation
 
-The `errorMessage` prop can be used to help the user fix a validation error. It should be combined with the `isInvalid` prop to
-semantically mark the checkbox group as invalid for assistive technologies.
+CheckboxGroup supports the `isRequired` prop to ensure the user selects at least one item, as well as custom client and server-side validation. Individual checkboxes also support validation, and errors from all checkboxes are aggregated at the group level. CheckboxGroup can also be integrated with other form libraries. See the [Forms](forms.html) guide to learn more.
+
+When a CheckboxGroup has the `validationBehavior="native"` prop, validation errors block form submission. The `isRequired` prop at the `CheckboxGroup` level requires that at least one item is selected. To display validation errors, use the `validationErrors` and `errorMessageProps` returned by `useCheckboxGroup`. This allows you to render error messages from all of the above sources with consistent custom styles.
 
 ```tsx example
-<CheckboxGroup label="Favorite sports" errorMessage="Invalid selection of sports." isInvalid>
-  <Checkbox value="soccer">Soccer</Checkbox>
-  <Checkbox value="baseball">Baseball</Checkbox>
-  <Checkbox value="basketball">Basketball</Checkbox>
-</CheckboxGroup>
+<form>
+  <CheckboxGroup
+    label="Sandwich condiments"
+    name="condiments"
+    /*- begin highlight -*/
+    isRequired
+    validationBehavior="native"
+    /*- end highlight -*/
+  >
+    <Checkbox value="lettuce">Lettuce</Checkbox>
+    <Checkbox value="tomato">Tomato</Checkbox>
+    <Checkbox value="onion">Onion</Checkbox>
+    <Checkbox value="sprouts">Sprouts</Checkbox>
+  </CheckboxGroup>
+  <input type="submit" style={{marginTop: 8}} />
+</form>
+```
+
+### Individual Checkbox validation
+
+To require that specific checkboxes are checked, set the `isRequired` prop at the `Checkbox` level instead of the `CheckboxGroup`. The following example shows how to require that all items are selected.
+
+```tsx example
+<form>
+  <CheckboxGroup label="Agree to the following" validationBehavior="native">
+    {/*- begin highlight -*/}
+    <Checkbox value="terms" isRequired>Terms and conditions</Checkbox>
+    <Checkbox value="privacy" isRequired>Privacy policy</Checkbox>
+    <Checkbox value="cookies" isRequired>Cookie policy</Checkbox>
+    {/*- end highlight -*/}
+  </CheckboxGroup>
+  <input type="submit" style={{marginTop: 8}} />
+</form>
 ```
 
 ### Disabled

packages/@react-aria/combobox/docs/useComboBox.mdx

@@ -74,7 +74,7 @@ A combo box can be built using the [<datalist>](https://developer.mozilla.
 * Virtual focus management for combo box list box option navigation
 * Hides elements outside the input and list box from assistive technology while the list box is open in a portal
 * Custom localized announcements for option focusing, filtering, and selection using an ARIA live region to work around VoiceOver bugs
-* Support for description and error message help text linked to the input via ARIA
+* Support for native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and server-side validation errors
 
 Read our [blog post](../blog/building-a-combobox.html) for more details about the interactions and accessibility features implemented by `useComboBox`.
 

packages/@react-aria/numberfield/docs/useNumberField.mdx

@@ -61,7 +61,7 @@ formatting options and can be styled as needed.
 * Follows the [spinbutton](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) ARIA pattern
 * Works around bugs in VoiceOver with the spinbutton role
 * Uses an ARIA live region to ensure that value changes are announced
-* Support for description and error message help text linked to the input via ARIA
+* Support for native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and server-side validation errors
 
 Read our [blog post](../blog/how-we-internationalized-our-numberfield.html) for more details about the interactions and internationalization support implemented by `useNumberField`.
 

packages/@react-aria/radio/docs/useRadioGroup.mdx

@@ -55,7 +55,7 @@ radio groups that can be styled as needed.
 * Radio groups are exposed to assistive technology via ARIA
 * Each radio is built with a native HTML `<input>` element, which can be optionally visually
   hidden to allow custom styling
-* Full support for browser features like form autofill
+* Full support for browser features like form autofill and validation
 * Keyboard focus management and cross browser normalization
 * Group and radio labeling support for assistive technology
 
@@ -162,9 +162,9 @@ import {useFocusRing} from '@react-aria/focus';
 let RadioContext = React.createContext(null);
 
 function RadioGroup(props) {
-  let {children, label, description, errorMessage} = props;
+  let {children, label, description} = props;
   let state = useRadioGroupState(props);
-  let {radioGroupProps, labelProps, descriptionProps, errorMessageProps} = useRadioGroup(props, state);
+  let {radioGroupProps, labelProps, descriptionProps, errorMessageProps, isInvalid, validationErrors} = useRadioGroup(props, state);
 
   return (
     <div {...radioGroupProps}>
@@ -173,8 +173,8 @@ function RadioGroup(props) {
         {children}
       </RadioContext.Provider>
       {description && <div {...descriptionProps} style={{fontSize: 12}}>{description}</div>}
-      {errorMessage && state.isInvalid &&
-        <div {...errorMessageProps} style={{color: 'red', fontSize: 12}}>{errorMessage}</div>
+      {isInvalid &&
+        <div {...errorMessageProps} style={{color: 'red', fontSize: 12}}>{validationErrors.join(' ')}</div>
       }
     </div>
   )
@@ -293,16 +293,23 @@ The `description` prop can be used to associate additional help text with a radi
 </RadioGroup>
 ```
 
-### Error message
+### Validation
 
-The `errorMessage` prop can be used to help the user fix a validation error. It should be combined with the `isInvalid` prop to
-semantically mark the radio group as invalid for assistive technologies.
+RadioGroup supports the `isRequired` prop to ensure the user selects an option, as well as custom client and server-side validation. It can also be integrated with other form libraries. See the [Forms](forms.html) guide to learn more.
+
+When a RadioGroup has the `validationBehavior="native"` prop, validation errors block form submission. To display validation errors, use the `validationErrors` and `errorMessageProps` returned by `useRadioGroup`. This allows you to render error messages from all of the above sources with consistent custom styles.
 
 ```tsx example
-<RadioGroup label="Favorite pet" errorMessage="Invalid pet selection." isInvalid>
-  <Radio value="dogs">Dogs</Radio>
-  <Radio value="cats">Cats</Radio>
-</RadioGroup>
+<form>
+  {/*- begin highlight -*/}
+  <RadioGroup label="Favorite pet" name="pet" isRequired validationBehavior="native">
+  {/*- end highlight -*/}
+    <Radio value="dogs">Dog</Radio>
+    <Radio value="cats">Cat</Radio>
+    <Radio value="dragon">Dragon</Radio>
+  </RadioGroup>
+  <input type="submit" style={{marginTop: 8}} />
+</form>
 ```
 
 ### Disabled

packages/@react-aria/searchfield/docs/useSearchField.mdx

@@ -50,7 +50,7 @@ search fields that can be styled as needed.
 * Keyboard submit handling via the <Keyboard>Enter</Keyboard> key
 * Keyboard support for clearing the search field with the <Keyboard>Escape</Keyboard> key
 * Custom clear button support with internationalized label for accessibility
-* Support for description and error message help text linked to the input via ARIA
+* Support for native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and server-side validation errors
 
 ## Anatomy
 

packages/@react-aria/select/docs/useSelect.mdx

@@ -58,7 +58,7 @@ select components that can be styled as needed without compromising on high qual
 * Support for disabled options
 * Support for sections
 * Labeling support for accessibility
-* Support for description and error message help text linked to the input via ARIA
+* Support for native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and server-side validation errors
 * Support for mouse, touch, and keyboard interactions
 * Tab stop focus management
 * Keyboard support for opening the listbox using the arrow keys, including automatically focusing

packages/@react-aria/textfield/docs/useTextField.mdx

@@ -48,7 +48,7 @@ allowing for custom styling.
 * Built with a native `<input>` or `<textarea>` element
 * Visual and ARIA labeling support
 * Change, clipboard, composition, selection, and input event support
-* Required and invalid states exposed to assistive technology via ARIA
+* Support for native HTML constraint validation with customizable UI, custom validation functions, realtime validation, and server-side validation errors
 * Support for description and error message help text linked to the input via ARIA
 
 ## Anatomy
@@ -78,21 +78,17 @@ to identify the element to screen readers.
 import type {AriaTextFieldProps} from '@react-aria/textfield';
 import {useTextField} from '@react-aria/textfield';
 
-interface TextFieldProps extends Omit<AriaTextFieldProps, 'errorMessage'> {
-  errorMessage?: string
-}
-
-function TextField(props: TextFieldProps) {
+function TextField(props: AriaTextFieldProps) {
   let {label} = props;
   let ref = React.useRef(null);
-  let {labelProps, inputProps, descriptionProps, errorMessageProps} = useTextField(props, ref);
+  let {labelProps, inputProps, descriptionProps, errorMessageProps, isInvalid, validationErrors} = useTextField(props, ref);
 
   return (
     <div style={{display: 'flex', flexDirection: 'column', width: 200}}>
       <label {...labelProps}>{label}</label>
       <input {...inputProps} ref={ref} />
       {props.description && <div {...descriptionProps} style={{fontSize: 12}}>{props.description}</div>}
-      {props.errorMessage && <div {...errorMessageProps} style={{color: 'red', fontSize: 12}}>{props.errorMessage}</div>}
+      {isInvalid && <div {...errorMessageProps} style={{color: 'red', fontSize: 12}}>{validationErrors.join(' ')}</div>}
     </div>
   );
 }
@@ -165,16 +161,25 @@ The `description` prop can be used to associate additional help text with a text
   description="Enter an email for us to contact you about your order." />
 ```
 
-### Error message
+### Validation
+
+useTextField supports HTML constraint validation props such as `isRequired`, `type="email"`, `minLength`, and `pattern`, as well as custom validation functions, realtime validation, and server-side validation. It can also be integrated with other form libraries. See the [Forms](forms.html) guide to learn more.
 
-The `errorMessage` prop can be used to help the user fix a validation error. It should be combined with the `isInvalid` prop to
-semantically mark the input element as invalid for assistive technologies.
+When a TextField has the `validationBehavior="native"` prop, validation errors block form submission. To display validation errors, use the `validationErrors` and `errorMessageProps` returned by `useTextField`. This allows you to render error messages from all of the above sources with consistent custom styles.
 
 ```tsx example
-<TextField
-  label="Email"
-  isInvalid
-  errorMessage="Please enter a valid email address." />
+<form>
+  <TextField
+    label="Email"
+    name="email"
+    /*- begin highlight -*/
+    type="email"
+    isRequired
+    validationBehavior="native"
+    /*- end highlight -*/
+  />
+  <input type="submit" style={{marginTop: 8}} />
+</form>
 ```
 
 ### Disabled

packages/dev/docs/pages/react-aria/forms.mdx

@@ -7,6 +7,9 @@ the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTA
 OF ANY KIND, either express or implied. See the License for the specific language
 governing permissions and limitations under the License. */}
 
+import sharedDocs from 'docs:@react-types/shared';
+import {TypeContext, InterfaceType} from '@react-spectrum/docs';
+
 import {Layout} from '@react-spectrum/docs';
 export default Layout;
 
@@ -500,3 +503,31 @@ function App() {
   );
 }
 ```
+
+## Hooks
+
+If you're using React Aria hooks rather than components, native form validation can be enabled using the `validationBehavior="native"` prop. Each hook returns validation information which can be used to render error messages with custom styles.
+
+```tsx
+let {isInvalid, validationErrors, validationDetails} = useTextField(props, ref);
+```
+
+<TypeContext.Provider value={sharedDocs.links}>
+  <InterfaceType properties={sharedDocs.exports.ValidationResult.properties} />
+</TypeContext.Provider>
+
+Server errors can be provided using the `FormValidationContext` directly, or using the `Form` component from `react-aria-components` as described above.
+
+```tsx
+import {FormValidationContext} from 'react-aria';
+
+<FormValidationContext.Provider value={{username: 'This username is taken.'}}>
+  <MyTextField
+    name="username"
+    isRequired
+    validationBehavior="native" />
+  {/* ... */}
+</FormValidationContext.Provider>
+```
+
+See the [useTextField](useTextField.html) docs for an example of how to render validation errors.