@react-aria/toast 3.0.0-alpha.0

package/src/useToast.ts

@@ -0,0 +1,111 @@
+/*
+ * 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 {AriaButtonProps} from '@react-types/button';
+import {AriaLabelingProps, DOMAttributes, FocusableElement} from '@react-types/shared';
+// @ts-ignore
+import intlMessages from '../intl/*.json';
+import {QueuedToast, ToastState} from '@react-stately/toast';
+import {RefObject, useEffect, useRef} from 'react';
+import {useId, useLayoutEffect, useSlotId} from '@react-aria/utils';
+import {useLocalizedStringFormatter} from '@react-aria/i18n';
+
+export interface AriaToastProps<T> extends AriaLabelingProps {
+  /** The toast object. */
+  toast: QueuedToast<T>
+}
+
+export interface ToastAria {
+  /** Props for the toast container element. */
+  toastProps: DOMAttributes,
+  /** Props for the toast title element. */
+  titleProps: DOMAttributes,
+  /** Props for the toast description element, if any. */
+  descriptionProps: DOMAttributes,
+  /** Props for the toast close button. */
+  closeButtonProps: AriaButtonProps
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a toast component.
+ * Toasts display brief, temporary notifications of actions, errors, or other events in an application.
+ */
+export function useToast<T>(props: AriaToastProps<T>, state: ToastState<T>, ref: RefObject<FocusableElement>): ToastAria {
+  let {
+    key,
+    timer,
+    timeout,
+    animation
+  } = props.toast;
+
+  useEffect(() => {
+    if (!timer) {
+      return;
+    }
+
+    timer.reset(timeout);
+    return () => {
+      timer.pause();
+    };
+  }, [timer, timeout]);
+
+  // Restore focus to the toast container on unmount.
+  // If there are no more toasts, the container will be unmounted
+  // and will restore focus to wherever focus was before the user
+  // focused the toast region.
+  let focusOnUnmount = useRef(null);
+  useLayoutEffect(() => {
+    let container = ref.current.closest('[role=region]') as HTMLElement;
+    return () => {
+      if (container && container.contains(document.activeElement)) {
+        // Focus must be delayed for focus ring to appear, but we can't wait
+        // until useEffect cleanup to check if focus was inside the container.
+        focusOnUnmount.current = container;
+      }
+    };
+  }, [ref]);
+
+  // eslint-disable-next-line
+  useEffect(() => {
+    return () => {
+      if (focusOnUnmount.current) {
+        focusOnUnmount.current.focus();
+      }
+    };
+  }, [ref]);
+
+  let titleId = useId();
+  let descriptionId = useSlotId();
+  let stringFormatter = useLocalizedStringFormatter(intlMessages);
+
+  return {
+    toastProps: {
+      role: 'alert',
+      'aria-label': props['aria-label'],
+      'aria-labelledby': props['aria-labelledby'] || titleId,
+      'aria-describedby': props['aria-describedby'] || descriptionId,
+      'aria-details': props['aria-details'],
+      // Hide toasts that are animating out so VoiceOver doesn't announce them.
+      'aria-hidden': animation === 'exiting' ? 'true' : undefined
+    },
+    titleProps: {
+      id: titleId
+    },
+    descriptionProps: {
+      id: descriptionId
+    },
+    closeButtonProps: {
+      'aria-label': stringFormatter.format('close'),
+      onPress: () => state.close(key)
+    }
+  };
+}

package/src/useToastRegion.ts

@@ -0,0 +1,79 @@
+import {AriaLabelingProps, DOMAttributes} from '@react-types/shared';
+import {focusWithoutScrolling, mergeProps} from '@react-aria/utils';
+import {getInteractionModality, useFocusWithin, useHover} from '@react-aria/interactions';
+// @ts-ignore
+import intlMessages from '../intl/*.json';
+import {RefObject, useEffect, useRef} from 'react';
+import {ToastState} from '@react-stately/toast';
+import {useLandmark} from '@react-aria/landmark';
+import {useLocalizedStringFormatter} from '@react-aria/i18n';
+
+export interface AriaToastRegionProps extends AriaLabelingProps {
+  /**
+   * An accessibility label for the toast region.
+   * @default "Notifications"
+   */
+  'aria-label'?: string
+}
+
+export interface ToastRegionAria {
+  /** Props for the landmark region element. */
+  regionProps: DOMAttributes
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a toast region containing one or more toasts.
+ * Toasts display brief, temporary notifications of actions, errors, or other events in an application.
+ */
+export function useToastRegion<T>(props: AriaToastRegionProps, state: ToastState<T>, ref: RefObject<HTMLElement>): ToastRegionAria {
+  let stringFormatter = useLocalizedStringFormatter(intlMessages);
+  let {landmarkProps} = useLandmark({
+    role: 'region',
+    'aria-label': props['aria-label'] || stringFormatter.format('notifications')
+  }, ref);
+
+  let {hoverProps} = useHover({
+    onHoverStart: state.pauseAll,
+    onHoverEnd: state.resumeAll
+  });
+
+  let lastFocused = useRef(null);
+  let {focusWithinProps} = useFocusWithin({
+    onFocusWithin: (e) => {
+      state.pauseAll();
+      lastFocused.current = e.relatedTarget;
+    },
+    onBlurWithin: () => {
+      state.resumeAll();
+      lastFocused.current = null;
+    }
+  });
+
+  // When the region unmounts, restore focus to the last element that had focus
+  // before the user moved focus into the region.
+  // TODO: handle when the element has unmounted like FocusScope does?
+  // eslint-disable-next-line arrow-body-style
+  useEffect(() => {
+    return () => {
+      if (lastFocused.current && document.body.contains(lastFocused.current)) {
+        if (getInteractionModality() === 'pointer') {
+          focusWithoutScrolling(lastFocused.current);
+        } else {
+          lastFocused.current.focus();
+        }
+      }
+    };
+  }, [ref]);
+
+  return {
+    regionProps: mergeProps(landmarkProps, hoverProps, focusWithinProps, {
+      tabIndex: -1,
+      // Mark the toast region as a "top layer", so that it:
+      //   - is not aria-hidden when opening an overlay
+      //   - allows focus even outside a containing focus scope
+      //   - doesn’t dismiss overlays when clicking on it, even though it is outside
+      // @ts-ignore
+      'data-react-aria-top-layer': true
+    })
+  };
+}