Refactor internal contexts to expose state publicly (#5052)

Author: devongovett

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

@@ -13,7 +13,7 @@
 import {AriaDateFieldProps as AriaDateFieldPropsBase, AriaTimeFieldProps, DateValue, TimeValue} from '@react-types/datepicker';
 import {createFocusManager, FocusManager} from '@react-aria/focus';
 import {DateFieldState, TimeFieldState} from '@react-stately/datepicker';
-import {DOMAttributes, KeyboardEvent} from '@react-types/shared';
+import {DOMAttributes, GroupDOMAttributes, KeyboardEvent} from '@react-types/shared';
 import {filterDOMProps, mergeProps, useDescription, useFormReset} from '@react-aria/utils';
 import {FocusEvent, InputHTMLAttributes, RefObject, useEffect, useMemo, useRef} from 'react';
 // @ts-ignore
@@ -33,7 +33,7 @@ export interface DateFieldAria {
    /** Props for the field's visible label element, if any. */
   labelProps: DOMAttributes,
    /** Props for the field grouping element. */
-  fieldProps: DOMAttributes,
+  fieldProps: GroupDOMAttributes,
   /** Props for the hidden input element for HTML form submission. */
   inputProps: InputHTMLAttributes<HTMLInputElement>,
   /** Props for the description element, if any. */
@@ -110,14 +110,14 @@ export function useDateField<T extends DateValue>(props: AriaDateFieldOptions<T>
   // rather than role="group". Since the date picker/date range picker already has a role="group"
   // with a label and description, and the segments are already labeled by this as well, this
   // avoids very verbose duplicate announcements.
-  let fieldDOMProps: DOMAttributes;
+  let fieldDOMProps: GroupDOMAttributes;
   if (props[roleSymbol] === 'presentation') {
     fieldDOMProps = {
       role: 'presentation'
     };
   } else {
     fieldDOMProps = mergeProps(fieldProps, {
-      role: 'group',
+      role: 'group' as const,
       'aria-disabled': props.isDisabled || undefined,
       'aria-describedby': describedBy
     });

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

@@ -297,7 +297,7 @@ export function useNumberField(props: AriaNumberFieldProps, state: NumberFieldSt
       ...focusWithinProps,
       role: 'group',
       'aria-disabled': isDisabled,
-      'aria-invalid': validationState === 'invalid' ? 'true' : undefined
+      'aria-invalid': isInvalid || validationState === 'invalid' ? 'true' : undefined
     },
     labelProps,
     inputProps,

packages/@react-stately/datepicker/src/useDatePickerState.ts

@@ -28,9 +28,9 @@ export interface DatePickerStateOptions<T extends DateValue> extends DatePickerP
 
 export interface DatePickerState extends OverlayTriggerState {
   /** The currently selected date. */
-  value: DateValue,
+  value: DateValue | null,
   /** Sets the selected date. */
-  setValue(value: DateValue): void,
+  setValue(value: DateValue | null): void,
   /**
    * The date portion of the value. This may be set prior to `value` if the user has
    * selected a date but has not yet selected a time.

packages/@react-stately/datepicker/src/useDateRangePickerState.ts

@@ -29,21 +29,21 @@ export interface DateRangePickerStateOptions<T extends DateValue = DateValue> ex
 type TimeRange = RangeValue<TimeValue>;
 export interface DateRangePickerState extends OverlayTriggerState {
   /** The currently selected date range. */
-  value: DateRange,
+  value: DateRange | null,
   /** Sets the selected date range. */
-  setValue(value: DateRange): void,
+  setValue(value: DateRange | null): void,
   /**
    * The date portion of the selected range. This may be set prior to `value` if the user has
    * selected a date range but has not yet selected a time range.
    */
-  dateRange: DateRange,
+  dateRange: DateRange | null,
   /** Sets the date portion of the selected range. */
   setDateRange(value: DateRange): void,
   /**
    * The time portion of the selected range. This may be set prior to `value` if the user has
    * selected a time range but has not yet selected a date range.
    */
-  timeRange: TimeRange,
+  timeRange: TimeRange | null,
   /** Sets the time portion of the selected range. */
   setTimeRange(value: TimeRange): void,
   /** Sets the date portion of either the start or end of the selected range. */
@@ -90,7 +90,7 @@ export function useDateRangePickerState<T extends DateValue = DateValue>(props:
   let value = controlledValue || placeholderValue;
 
   let setValue = (value: DateRange) => {
-    setPlaceholderValue(value);
+    setPlaceholderValue(value || {start: null, end: null});
     if (value?.start && value.end) {
       setControlledValue(value);
     } else {

packages/@react-stately/list/src/useSingleSelectListState.ts

@@ -27,7 +27,7 @@ export interface SingleSelectListState<T> extends ListState<T> {
   readonly selectedKey: Key,
 
   /** Sets the selected key. */
-  setSelectedKey(key: Key): void,
+  setSelectedKey(key: Key | null): void,
 
   /** The value of the currently selected item. */
   readonly selectedItem: Node<T>

packages/@react-stately/selection/src/types.ts

@@ -32,7 +32,7 @@ export interface SingleSelectionState extends FocusState {
   /** The currently selected key in the collection. */
   readonly selectedKey: Key,
   /** Sets the selected key in the collection. */
-  setSelectedKey(key: Key): void
+  setSelectedKey(key: Key | null): void
 }
 
 export interface MultipleSelectionState extends FocusState {

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

@@ -12,6 +12,7 @@ export default Layout;
 
 import docs from 'docs:react-aria-components';
 import i18nDocs from 'docs:@internationalized/date';
+import ariaDocs from 'docs:@react-aria/calendar';
 import statelyDocs from 'docs:@react-stately/calendar';
 import {PropTable, HeaderInfo, TypeLink, PageDescription, StateTable, ContextTable} from '@react-spectrum/docs';
 import styles from '@react-spectrum/docs/src/docs.css';
@@ -767,7 +768,7 @@ interface PresetProps {
 
 function Preset({date, children}: PresetProps) {
   /*- begin highlight -*/
-  let context = useSlottedContext(CalendarContext);
+  let context = useSlottedContext(CalendarContext)!;
   /*- end highlight -*/
   let onPress = () => {
     context.onFocusChange(date);
@@ -848,20 +849,53 @@ Now you can use `MyCustomHeading` within a `Calendar`, in place of the builtin R
 </Calendar>
 ```
 
+### State
+
+Calendar provides a <TypeLink links={statelyDocs.links} type={statelyDocs.exports.CalendarState} /> object to its children via `CalendarStateContext`. This can be used to access and manipulate the calendar's state.
+
+This example shows a `CalendarValue` component that can be placed within a `Calendar` to display the currently selected date as a formatted string.
+
+```tsx example
+import {CalendarStateContext} from 'react-aria-components';
+import {useDateFormatter} from 'react-aria';
+
+function CalendarValue() {
+  /*- begin highlight -*/
+  let state = React.useContext(CalendarStateContext)!;
+  /*- end highlight -*/
+  let date = state.value?.toDate(getLocalTimeZone());
+  let formatted = date ? useDateFormatter().format(date) : 'None';
+  return <small>Selected date: {formatted}</small>;
+}
+
+<Calendar>
+  <header>
+    <Button slot="previous">◀</Button>
+    <Heading />
+    <Button slot="next">▶</Button>
+  </header>
+  <CalendarGrid>
+    {date => <CalendarCell date={date} />}
+  </CalendarGrid>
+  {/*- begin highlight -*/}
+  <CalendarValue />
+  {/*- end highlight -*/}
+</Calendar>
+```
+
 ### Hooks
 
-If you need to customize things even further, such as accessing internal state or customizing DOM structure, you can drop down to the lower level Hook-based API. See [useCalendar](useCalendar.html) for more details. This example uses the `useCalendarGrid` hook to build a single week calendar view.
+If you need to customize things even further, such as accessing internal state or customizing DOM structure, you can drop down to the lower level Hook-based API. See [useCalendar](useCalendar.html) for more details.
+
+This example uses the <TypeLink links={ariaDocs.links} type={ariaDocs.exports.useCalendarGrid} /> hook to build a single week calendar view.
 
 ```tsx example render=false export=true
 import type {CalendarGridProps} from 'react-aria-components';
-import type {CalendarState} from 'react-stately';
+import {CalendarStateContext} from 'react-aria-components';
 import {useCalendarGrid} from 'react-aria';
 
-interface WeekCalendarGridProps extends CalendarGridProps {
-  state: CalendarState
-}
-
-function WeekCalendarGrid({state, ...props}: WeekCalendarGridProps) {
+function WeekCalendarGrid(props: CalendarGridProps) {
+  let state = React.useContext(CalendarStateContext)!;
   let {gridProps} = useCalendarGrid(props, state);
 
   return (
@@ -880,14 +914,12 @@ function WeekCalendarGrid({state, ...props}: WeekCalendarGridProps) {
 
 ```tsx example
 <Calendar visibleDuration={{weeks: 1}} defaultValue={today(getLocalTimeZone())}>
-  {({state}) => (
-    <div className="week">
-      <Heading />
-      <Button slot="previous">◀</Button>
-      <WeekCalendarGrid state={state} />
-      <Button slot="next">▶</Button>
-    </div>
-  )}
+  <div className="week">
+    <Heading />
+    <Button slot="previous">◀</Button>
+    <WeekCalendarGrid />
+    <Button slot="next">▶</Button>
+  </div>
 </Calendar>
 ```
 

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

@@ -648,6 +648,31 @@ Now you can use `MyCustomLabel` within a `CheckboxGroup`, in place of the builti
 </CheckboxGroup>
 ```
 
+### State
+
+CheckboxGroup provides a <TypeLink links={statelyDocs.links} type={statelyDocs.exports.CheckboxGroupState} /> object to its children via `CheckboxGroupStateContext`. This can be used to access and manipulate the checkbox group's state.
+
+This example shows a `SelectionCount` component that can be placed within a `CheckboxGroup` to display the number of selected items.
+
+```tsx example
+import {CheckboxGroupStateContext} from 'react-aria-components';
+
+function SelectionCount() {
+  /*- begin highlight -*/
+  let state = React.useContext(CheckboxGroupStateContext)!;
+  /*- end highlight -*/
+  return <small>{state.value.length} items selected.</small>;
+}
+
+<MyCheckboxGroup label="Sandwich condiments">
+  <MyCheckbox value="lettuce">Lettuce</MyCheckbox>
+  <MyCheckbox value="tomato">Tomato</MyCheckbox>
+  <MyCheckbox value="onion">Onion</MyCheckbox>
+  <MyCheckbox value="sprouts">Sprouts</MyCheckbox>
+  <SelectionCount />
+</MyCheckboxGroup>
+```
+
 ### Hooks
 
 If you need to customize things further, such as accessing internal state or customizing DOM structure, you can drop down to the lower level Hook-based API. See [useCheckboxGroup](useCheckboxGroup.html) for more details.

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

@@ -1319,6 +1319,86 @@ Now you can use `MyCustomLabel` within a `ComboBox`, in place of the builtin Rea
 </ComboBox>
 ```
 
+### State
+
+ComboBox provides an <TypeLink links={statelyDocs.links} type={statelyDocs.exports.ComboBoxState} /> object to its children via `ComboBoxStateContext`. This can be used to access and manipulate the combo box's state.
+
+This example shows a `ComboBoxClearButton` component that can be placed within a `ComboBox` to allow the user to clear the selected value.
+
+```tsx example
+import {ComboBoxStateContext} from 'react-aria-components';
+
+function ComboBoxClearButton() {
+  /*- begin highlight -*/
+  let state = React.useContext(ComboBoxStateContext);
+  /*- end highlight -*/
+  return (
+    <Button
+      // Don't inherit default Button behavior from ComboBox.
+      slot={null}
+      className="clear-button"
+      aria-label="Clear"
+      onPress={() => state?.setSelectedKey(null)}>
+      ✕
+    </Button>
+  );
+}
+
+<ComboBox defaultSelectedKey="cat">
+  <Label>Favorite Animal</Label>
+  <div>
+    <Input />
+    {/*- begin highlight -*/}
+    <ComboBoxClearButton />
+    {/*- end highlight -*/}
+    <Button>▼</Button>
+  </div>
+  <Popover>
+    <ListBox>
+      <Item id="cat">Cat</Item>
+      <Item id="dog">Dog</Item>
+      <Item id="kangaroo">Kangaroo</Item>
+    </ListBox>
+  </Popover>
+</ComboBox>
+```
+
+<details>
+  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> Show CSS</summary>
+
+```css
+.clear-button {
+  width: 1.143rem;
+  height: 1.143rem;
+  border-radius: 1.143rem;
+  margin-left: -3.143rem;
+  font-size: 0.857rem;
+  line-height: 0.857rem;
+  vertical-align: middle;
+  text-align: center;
+  background: gray;
+  color: white;
+  border: none;
+  padding: 0;
+  outline: none;
+
+  &[data-pressed] {
+    background: dimgray;
+  }
+
+  &[data-focus-visible] {
+    outline: 2px solid slateblue;
+    outline-offset: 2px;
+  }
+
+  + .react-aria-Button {
+    margin-left: 4px;
+  }
+}
+```
+
+</details>
+
 ### Hooks
 
 If you need to customize things even further, such as accessing internal state, intercepting events, or customizing the DOM structure, you can drop down to the lower level Hook-based API. See [useComboBox](useComboBox.html) for more details.

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

@@ -718,6 +718,37 @@ Now you can use `MyCustomLabel` within a `DateField`, in place of the builtin Re
 </DateField>
 ```
 
+### State
+
+DateField provides a <TypeLink links={statelyDocs.links} type={statelyDocs.exports.DateFieldState} /> object to its children via `DateFieldStateContext`. This can be used to access and manipulate the date field's state.
+
+This example shows a `DateFormat` component that can be placed within a `DateField` to display the expected date format.
+
+```tsx example
+import {DateFieldStateContext} from 'react-aria-components';
+import {useLocale} from 'react-aria';
+
+function DateFormat() {
+  /*- begin highlight -*/
+  let state = React.useContext(DateFieldStateContext)!;
+  /*- end highlight -*/
+  let {locale} = useLocale();
+  let displayNames = new Intl.DisplayNames(locale, {type: 'dateTimeField'});
+  let format = state.segments.map(segment => segment.type === 'literal' ? segment.text : displayNames.of(segment.type)).join(' ');
+  return <small>{format}</small>;
+}
+
+<DateField defaultValue={today(getLocalTimeZone())}>
+  <Label>Date</Label>
+  <DateInput>
+    {segment => <DateSegment segment={segment} />}
+  </DateInput>
+  {/*- begin highlight -*/}
+  <DateFormat />
+  {/*- end highlight -*/}
+</DateField>
+```
+
 ### Hooks
 
 If you need to customize things even further, such as accessing internal state or customizing DOM structure, you can drop down to the lower level Hook-based API. See [useDateField](useDateField.html) for more details.