Add docs for the Group component (#5060)

Author: devongovett

packages/@react-aria/datepicker/src/useDatePicker.ts

@@ -16,7 +16,7 @@ import {AriaDialogProps} from '@react-types/dialog';
 import {CalendarProps} from '@react-types/calendar';
 import {createFocusManager} from '@react-aria/focus';
 import {DatePickerState} from '@react-stately/datepicker';
-import {DOMAttributes, KeyboardEvent} from '@react-types/shared';
+import {DOMAttributes, GroupDOMAttributes, KeyboardEvent} from '@react-types/shared';
 import {filterDOMProps, mergeProps, useDescription, useId} from '@react-aria/utils';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
@@ -31,7 +31,7 @@ export interface DatePickerAria {
   /** Props for the date picker's visible label element, if any. */
   labelProps: DOMAttributes,
   /** Props for the grouping element containing the date field and button. */
-  groupProps: DOMAttributes,
+  groupProps: GroupDOMAttributes,
   /** Props for the date field. */
   fieldProps: AriaDatePickerProps<DateValue>,
   /** Props for the popover trigger button. */
@@ -83,7 +83,7 @@ export function useDatePicker<T extends DateValue>(props: AriaDatePickerProps<T>
 
   return {
     groupProps: mergeProps(domProps, groupProps, fieldProps, descProps, focusWithinProps, {
-      role: 'group',
+      role: 'group' as const,
       'aria-disabled': props.isDisabled || null,
       'aria-labelledby': labelledBy,
       'aria-describedby': ariaDescribedBy,

packages/@react-aria/datepicker/src/useDateRangePicker.ts

@@ -15,7 +15,7 @@ import {AriaDatePickerProps, AriaDateRangePickerProps, DateValue} from '@react-t
 import {AriaDialogProps} from '@react-types/dialog';
 import {createFocusManager} from '@react-aria/focus';
 import {DateRangePickerState} from '@react-stately/datepicker';
-import {DOMAttributes, KeyboardEvent} from '@react-types/shared';
+import {DOMAttributes, GroupDOMAttributes, KeyboardEvent} from '@react-types/shared';
 import {filterDOMProps, mergeProps, useDescription, useId} from '@react-aria/utils';
 import {focusManagerSymbol, roleSymbol} from './useDateField';
 // @ts-ignore
@@ -31,7 +31,7 @@ export interface DateRangePickerAria {
   /** Props for the date range picker's visible label element, if any. */
   labelProps: DOMAttributes,
   /** Props for the grouping element containing the date fields and button. */
-  groupProps: DOMAttributes,
+  groupProps: GroupDOMAttributes,
   /** Props for the start date field. */
   startFieldProps: AriaDatePickerProps<DateValue>,
   /** Props for the end date field. */
@@ -117,7 +117,7 @@ export function useDateRangePicker<T extends DateValue>(props: AriaDateRangePick
 
   return {
     groupProps: mergeProps(domProps, groupProps, fieldProps, descProps, focusWithinProps, {
-      role: 'group',
+      role: 'group' as const,
       'aria-disabled': props.isDisabled || null,
       'aria-describedby': ariaDescribedBy,
       onKeyDown(e: KeyboardEvent) {

packages/@react-aria/numberfield/src/useNumberField.ts

@@ -12,7 +12,7 @@
 
 import {AriaButtonProps} from '@react-types/button';
 import {AriaNumberFieldProps} from '@react-types/numberfield';
-import {DOMAttributes, TextInputDOMProps} from '@react-types/shared';
+import {DOMAttributes, GroupDOMAttributes, TextInputDOMProps} from '@react-types/shared';
 import {filterDOMProps, isAndroid, isIOS, isIPhone, mergeProps, useFormReset, useId} from '@react-aria/utils';
 import {
   InputHTMLAttributes,
@@ -37,7 +37,7 @@ export interface NumberFieldAria {
   /** Props for the label element. */
   labelProps: LabelHTMLAttributes<HTMLLabelElement>,
   /** Props for the group wrapper around the input and stepper buttons. */
-  groupProps: DOMAttributes,
+  groupProps: GroupDOMAttributes,
   /** Props for the input element. */
   inputProps: InputHTMLAttributes<HTMLInputElement>,
   /** Props for the increment button, to be passed to [useButton](useButton.html). */
@@ -294,10 +294,10 @@ export function useNumberField(props: AriaNumberFieldProps, state: NumberFieldSt
 
   return {
     groupProps: {
+      ...focusWithinProps,
       role: 'group',
       'aria-disabled': isDisabled,
-      'aria-invalid': validationState === 'invalid' ? 'true' : undefined,
-      ...focusWithinProps
+      'aria-invalid': validationState === 'invalid' ? 'true' : undefined
     },
     labelProps,
     inputProps,

packages/@react-types/shared/src/dom.d.ts

@@ -178,3 +178,7 @@ export interface DOMAttributes<T = FocusableElement> extends AriaAttributes, Rea
   style?: CSSProperties | undefined,
   className?: string | undefined
 }
+
+export interface GroupDOMAttributes extends Omit<DOMAttributes<HTMLElement>, 'role'> {
+  role?: 'group' | 'region' | 'presentation'
+}

packages/react-aria-components/docs/Group.mdx

@@ -0,0 +1,274 @@
+{/* 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 {Layout} from '@react-spectrum/docs';
+export default Layout;
+
+import docs from 'docs:react-aria-components';
+import {PropTable, HeaderInfo, TypeLink, PageDescription, StateTable, ContextTable} from '@react-spectrum/docs';
+import styles from '@react-spectrum/docs/src/docs.css';
+import packageData from 'react-aria-components/package.json';
+import ChevronRight from '@spectrum-icons/workflow/ChevronRight';
+import {Divider} from '@react-spectrum/divider';
+import {Keyboard} from '@react-spectrum/text';
+
+---
+category: Content
+keywords: [group, aria]
+type: component
+---
+
+# Group
+
+<PageDescription>{docs.exports.Group.description}</PageDescription>
+
+<HeaderInfo
+  packageData={packageData}
+  componentNames={['Group']}
+  sourceData={[
+    {type: 'W3C', url: 'https://w3c.github.io/aria/#group'}
+  ]} />
+
+## Example
+
+```tsx example
+import {TextField, Label, Group, Input, Button} from 'react-aria-components';
+
+<TextField>
+  <Label>Email</Label>
+  <Group>
+    <Input />
+    <Button aria-label="Add email">➕</Button>
+  </Group>
+</TextField>
+```
+
+<details>
+  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> Show CSS</summary>
+
+```css
+.react-aria-Group {
+  --field-border: var(--spectrum-alias-border-color);
+  --field-border-hovered: var(--spectrum-alias-border-color-hover);
+  --field-background: var(--spectrum-global-color-gray-50);
+  --text-color: var(--spectrum-alias-text-color);
+  --text-color-disabled: var(--spectrum-alias-text-color-disabled);
+  --focus-ring-color: slateblue;
+  --invalid-color: var(--spectrum-global-color-red-600);
+
+  display: flex;
+  align-items: center;
+  width: fit-content;
+  border-radius: 6px;
+  border: 1px solid var(--field-border);
+  background: var(--field-background);
+  overflow: hidden;
+
+  &[data-hovered] {
+    border-color: var(--field-border-hovered);
+  }
+
+  &[data-focus-within] {
+    border-color: var(--focus-ring-color);
+    box-shadow: 0 0 0 1px var(--focus-ring-color);
+  }
+
+  .react-aria-Input {
+    padding: 0.286rem;
+    margin: 0;
+    font-size: 1rem;
+    color: var(--text-color);
+    outline: none;
+    border: none;
+    background: transparent;
+
+    &::placeholder {
+      color: var(--spectrum-gray-600);
+    }
+  }
+
+  .react-aria-Button {
+    padding: 0 6px;
+    border-width: 0 0 0 1px;
+    border-radius: 0 6px 6px 0;
+    align-self: stretch;
+  }
+}
+
+.react-aria-Button {
+  --border-color: var(--spectrum-alias-border-color);
+  --border-color-pressed: var(--spectrum-alias-border-color-down);
+  --border-color-disabled: var(--spectrum-alias-border-color-disabled);
+  --background-color: var(--spectrum-global-color-gray-50);
+  --background-color-pressed: var(--spectrum-global-color-gray-100);
+  --text-color: var(--spectrum-alias-text-color);
+  --text-color-disabled: var(--spectrum-alias-text-color-disabled);
+  --focus-ring-color: slateblue;
+
+  color: var(--text-color);
+  background: var(--background-color);
+  border: 1px solid var(--border-color);
+  border-radius: 4px;
+  appearance: none;
+  vertical-align: middle;
+  font-size: 1rem;
+  text-align: center;
+  margin: 0;
+  outline: none;
+  padding: 6px 10px;
+  text-decoration: none;
+
+  &[data-pressed] {
+    box-shadow: inset 0 1px 2px rgb(0 0 0 / 0.1);
+    background: var(--background-color-pressed);
+    border-color: var(--border-color-pressed);
+  }
+
+  &[data-focus-visible] {
+    border-color: var(--focus-ring-color);
+    box-shadow: 0 0 0 1px var(--focus-ring-color);
+  }
+}
+
+@media (forced-colors: active) {
+  .react-aria-TextField {
+    --field-border: ButtonBorder;
+    --field-border-disabled: GrayText;
+    --field-background: Field;
+    --text-color: FieldText;
+    --text-color-disabled: GrayText;
+    --focus-ring-color: Highlight;
+    --invalid-color: LinkText;
+  }
+}
+```
+
+</details>
+
+## Features
+
+A group can be created with a `<div role="group">` or via the HTML [&lt;fieldset&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset) element. The `Group` component supports additional UI states, and can be used standalone or as part of a larger pattern such as [NumberField](NumberField.html) or [DatePicker](Datepicker.html).
+
+* **Styleable** – Hover, keyboard focus, disabled, and invalid states are provided for easy styling. These states only apply when interacting with an appropriate input device, unlike CSS pseudo classes.
+* **Accessible** – Implemented using the ARIA "group" role by default, with optional support for the "region" landmark role.
+
+## Anatomy
+
+A group consists of a container element for a set of semantically related UI controls. It supports states such as hover, focus within, and disabled, which are useful to style visually adjoined children.
+
+```tsx
+import {Group} from 'react-aria-components';
+
+<Group>
+  {/* ... */}
+</Group>
+```
+
+## Accessibility
+
+### Labeling
+
+Group accepts the `aria-label` and `aria-labelledby` attributes to provide an accessible label to the group as a whole. This is read by assistive technology when navigating into the group from outside. When the labels of each child element of the group do not provide sufficient context on their own, the group should receive an additional label.
+
+```tsx example
+<span id="label-id">Serial number</span>
+<Group aria-labelledby="label-id">
+  <Input size={3} aria-label="First 3 digits" placeholder="000" />
+  –
+  <Input size={2} aria-label="Middle 2 digits" placeholder="00" />
+  –
+  <Input size={4} aria-label="Last 4 digits" placeholder="0000" />
+</Group>
+```
+
+### Role
+
+By default, `Group` uses the [group](https://w3c.github.io/aria/#group) ARIA role. If the contents of the group is important enough to be included in the page table of contents, use `role="region"` instead, and ensure that an `aria-label` or `aria-labelledby` prop is assigned.
+
+```tsx
+<Group role="region" aria-label="Object details">
+  {/* ... */}
+</Group>
+```
+
+If the `Group` component is used for styling purposes only, and does not include a set of related UI controls, then use `role="presentation"` instead.
+
+## Props
+
+<PropTable component={docs.exports.Group} links={docs.links} />
+
+## Styling
+
+React Aria components can be styled in many ways, including using CSS classes, inline styles, utility classes (e.g. Tailwind), CSS-in-JS (e.g. Styled Components), etc. By default, all components include a builtin `className` attribute which can be targeted using CSS selectors. These follow the `react-aria-ComponentName` naming convention.
+
+```css
+.react-aria-Group {
+  /* ... */
+}
+```
+
+A custom `className` can also be specified on any component. This overrides the default `className` provided by React Aria with your own.
+
+```jsx
+<Group className="my-group">
+  {/* ... */}
+</Group>
+```
+
+In addition, some components support multiple UI states (e.g. focused, placeholder, readonly, etc.). React Aria components expose states using data attributes, which you can target in CSS selectors. For example:
+
+```css
+.react-aria-Group[data-hovered] {
+  /* ... */
+}
+
+.react-aria-Group[data-focus-visible] {
+  /* ... */
+}
+```
+
+The states, selectors, and render props for `Group` are documented below.
+
+<StateTable properties={docs.exports.GroupRenderProps.properties} />
+
+## Advanced customization
+
+### Contexts
+
+All React Aria Components export a corresponding context that can be used to send props to them from a parent element. This enables you to build your own compositional APIs similar to those found in React Aria Components itself. You can send any prop or ref via context that you could pass to the corresponding component. The local props and ref on the component are merged with the ones passed via context, with the local props taking precedence (following the rules documented in [mergeProps](mergeProps.html)).
+
+<ContextTable components={['Group']} docs={docs} />
+
+This example shows a `LabeledGroup` component that accepts a label and a group as children. It uses the [useId](useId.html) hook to generate a unique id for the label, and provides this to the group via the `aria-labelledby` prop.
+
+```tsx example
+import {LabelContext, GroupContext} from 'react-aria-components';
+import {useId} from 'react-aria';
+
+function LabeledGroup({children}) {
+  let labelId = useId();
+
+  return (
+    <LabelContext.Provider value={{id: labelId, elementType: 'span'}}>
+      <GroupContext.Provider value={{'aria-labelledby': labelId}}>
+        {children}
+      </GroupContext.Provider>
+    </LabelContext.Provider>
+  );
+}
+
+<LabeledGroup>
+  <Label>Expiration date</Label>
+  <Group>
+    <Input size={3} aria-label="Month" placeholder="mm" />
+    /
+    <Input size={4} aria-label="Year" placeholder="yyyy" />
+  </Group>
+</LabeledGroup>
+```