@react-aria/focus 3.0.0-nightly-641446f65-240905

package/src/focusSafely.ts

@@ -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 {FocusableElement} from '@react-types/shared';
+import {focusWithoutScrolling, getOwnerDocument, runAfterTransition} from '@react-aria/utils';
+import {getInteractionModality} from '@react-aria/interactions';
+
+/**
+ * A utility function that focuses an element while avoiding undesired side effects such
+ * as page scrolling and screen reader issues with CSS transitions.
+ */
+export function focusSafely(element: FocusableElement) {
+  // If the user is interacting with a virtual cursor, e.g. screen reader, then
+  // wait until after any animated transitions that are currently occurring on
+  // the page before shifting focus. This avoids issues with VoiceOver on iOS
+  // causing the page to scroll when moving focus if the element is transitioning
+  // from off the screen.
+  const ownerDocument = getOwnerDocument(element);
+  if (getInteractionModality() === 'virtual') {
+    let lastFocusedElement = ownerDocument.activeElement;
+    runAfterTransition(() => {
+      // If focus did not move and the element is still in the document, focus it.
+      if (ownerDocument.activeElement === lastFocusedElement && element.isConnected) {
+        focusWithoutScrolling(element);
+      }
+    });
+  } else {
+    focusWithoutScrolling(element);
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/*
+ * 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.
+ */
+
+export {FocusScope, useFocusManager, getFocusableTreeWalker, createFocusManager, isElementInChildOfActiveScope, isFocusable} from './FocusScope';
+export {FocusRing} from './FocusRing';
+export {FocusableProvider, useFocusable} from './useFocusable';
+export {useFocusRing} from './useFocusRing';
+export {focusSafely} from './focusSafely';
+export {useHasTabbableChild} from './useHasTabbableChild';
+
+export type {FocusScopeProps, FocusManager, FocusManagerOptions} from './FocusScope';
+export type {FocusRingProps} from './FocusRing';
+export type {FocusableAria, FocusableOptions, FocusableProviderProps} from './useFocusable';
+export type {AriaFocusRingProps, FocusRingAria} from './useFocusRing';

package/src/isElementVisible.ts

@@ -0,0 +1,69 @@
+/*
+ * 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 {getOwnerWindow} from '@react-aria/utils';
+
+function isStyleVisible(element: Element) {
+  const windowObject = getOwnerWindow(element);
+  if (!(element instanceof windowObject.HTMLElement) && !(element instanceof windowObject.SVGElement)) {
+    return false;
+  }
+
+  let {display, visibility} = element.style;
+
+  let isVisible = (
+    display !== 'none' &&
+    visibility !== 'hidden' &&
+    visibility !== 'collapse'
+  );
+
+  if (isVisible) {
+    const {getComputedStyle} = element.ownerDocument.defaultView as unknown as Window;
+    let {display: computedDisplay, visibility: computedVisibility} = getComputedStyle(element);
+
+    isVisible = (
+      computedDisplay !== 'none' &&
+      computedVisibility !== 'hidden' &&
+      computedVisibility !== 'collapse'
+    );
+  }
+
+  return isVisible;
+}
+
+function isAttributeVisible(element: Element, childElement?: Element) {
+  return (
+    !element.hasAttribute('hidden') &&
+    // Ignore HiddenSelect when tree walking.
+    !element.hasAttribute('data-react-aria-prevent-focus') &&
+    (element.nodeName === 'DETAILS' &&
+      childElement &&
+      childElement.nodeName !== 'SUMMARY'
+      ? element.hasAttribute('open')
+      : true)
+  );
+}
+
+/**
+ * Adapted from https://github.com/testing-library/jest-dom and
+ * https://github.com/vuejs/vue-test-utils-next/.
+ * Licensed under the MIT License.
+ * @param element - Element to evaluate for display or visibility.
+ */
+export function isElementVisible(element: Element, childElement?: Element) {
+  return (
+    element.nodeName !== '#comment' &&
+    isStyleVisible(element) &&
+    isAttributeVisible(element, childElement) &&
+    (!element.parentElement || isElementVisible(element.parentElement, element))
+  );
+}

package/src/useFocusRing.ts

@@ -0,0 +1,78 @@
+import {DOMAttributes} from '@react-types/shared';
+import {isFocusVisible, useFocus, useFocusVisibleListener, useFocusWithin} from '@react-aria/interactions';
+import {useCallback, useRef, useState} from 'react';
+
+export interface AriaFocusRingProps {
+  /**
+   * Whether to show the focus ring when something
+   * inside the container element has focus (true), or
+   * only if the container itself has focus (false).
+   * @default 'false'
+   */
+  within?: boolean,
+
+  /** Whether the element is a text input. */
+  isTextInput?: boolean,
+
+  /** Whether the element will be auto focused. */
+  autoFocus?: boolean
+}
+
+export interface FocusRingAria {
+  /** Whether the element is currently focused. */
+  isFocused: boolean,
+
+  /** Whether keyboard focus should be visible. */
+  isFocusVisible: boolean,
+
+  /** Props to apply to the container element with the focus ring. */
+  focusProps: DOMAttributes
+}
+
+/**
+ * Determines whether a focus ring should be shown to indicate keyboard focus.
+ * Focus rings are visible only when the user is interacting with a keyboard,
+ * not with a mouse, touch, or other input methods.
+ */
+export function useFocusRing(props: AriaFocusRingProps = {}): FocusRingAria {
+  let {
+    autoFocus = false,
+    isTextInput,
+    within
+  } = props;
+  let state = useRef({
+    isFocused: false,
+    isFocusVisible: autoFocus || isFocusVisible()
+  });
+  let [isFocused, setFocused] = useState(false);
+  let [isFocusVisibleState, setFocusVisible] = useState(() => state.current.isFocused && state.current.isFocusVisible);
+
+  let updateState = useCallback(() => setFocusVisible(state.current.isFocused && state.current.isFocusVisible), []);
+
+  let onFocusChange = useCallback(isFocused => {
+    state.current.isFocused = isFocused;
+    setFocused(isFocused);
+    updateState();
+  }, [updateState]);
+
+  useFocusVisibleListener((isFocusVisible) => {
+    state.current.isFocusVisible = isFocusVisible;
+    updateState();
+  }, [], {isTextInput});
+
+  let {focusProps} = useFocus({
+    isDisabled: within,
+    onFocusChange
+  });
+
+  let {focusWithinProps} = useFocusWithin({
+    isDisabled: !within,
+    onFocusWithinChange: onFocusChange
+  });
+
+  return {
+    isFocused,
+    isFocusVisible: isFocusVisibleState,
+    focusProps: within ? focusWithinProps : focusProps
+  };
+}

package/src/useFocusable.tsx

@@ -0,0 +1,97 @@
+/*
+ * 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 {DOMAttributes, FocusableDOMProps, FocusableElement, FocusableProps, RefObject} from '@react-types/shared';
+import {focusSafely} from './';
+import {mergeProps, useObjectRef, useSyncRef} from '@react-aria/utils';
+import React, {ForwardedRef, MutableRefObject, ReactNode, useContext, useEffect, useRef} from 'react';
+import {useFocus, useKeyboard} from '@react-aria/interactions';
+
+export interface FocusableOptions extends FocusableProps, FocusableDOMProps {
+  /** Whether focus should be disabled. */
+  isDisabled?: boolean
+}
+
+export interface FocusableProviderProps extends DOMAttributes {
+  /** The child element to provide DOM props to. */
+  children?: ReactNode
+}
+
+interface FocusableContextValue extends FocusableProviderProps {
+  ref?: MutableRefObject<FocusableElement | null>
+}
+
+let FocusableContext = React.createContext<FocusableContextValue | null>(null);
+
+function useFocusableContext(ref: RefObject<FocusableElement | null>): FocusableContextValue {
+  let context = useContext(FocusableContext) || {};
+  useSyncRef(context, ref);
+
+  // eslint-disable-next-line
+  let {ref: _, ...otherProps} = context;
+  return otherProps;
+}
+
+/**
+ * Provides DOM props to the nearest focusable child.
+ */
+function FocusableProvider(props: FocusableProviderProps, ref: ForwardedRef<FocusableElement>) {
+  let {children, ...otherProps} = props;
+  let objRef = useObjectRef(ref);
+  let context = {
+    ...otherProps,
+    ref: objRef
+  };
+
+  return (
+    <FocusableContext.Provider value={context}>
+      {children}
+    </FocusableContext.Provider>
+  );
+}
+
+let _FocusableProvider = React.forwardRef(FocusableProvider);
+export {_FocusableProvider as FocusableProvider};
+
+export interface FocusableAria {
+  /** Props for the focusable element. */
+  focusableProps: DOMAttributes
+}
+
+/**
+ * Used to make an element focusable and capable of auto focus.
+ */
+export function useFocusable(props: FocusableOptions, domRef: RefObject<FocusableElement | null>): FocusableAria {
+  let {focusProps} = useFocus(props);
+  let {keyboardProps} = useKeyboard(props);
+  let interactions = mergeProps(focusProps, keyboardProps);
+  let domProps = useFocusableContext(domRef);
+  let interactionProps = props.isDisabled ? {} : domProps;
+  let autoFocusRef = useRef(props.autoFocus);
+
+  useEffect(() => {
+    if (autoFocusRef.current && domRef.current) {
+      focusSafely(domRef.current);
+    }
+    autoFocusRef.current = false;
+  }, [domRef]);
+
+  return {
+    focusableProps: mergeProps(
+      {
+        ...interactions,
+        tabIndex: props.excludeFromTabOrder && !props.isDisabled ? -1 : undefined
+      },
+      interactionProps
+    )
+  };
+}

package/src/useHasTabbableChild.ts

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2022 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 {getFocusableTreeWalker} from './FocusScope';
+import {RefObject} from '@react-types/shared';
+import {useLayoutEffect} from '@react-aria/utils';
+import {useState} from 'react';
+
+interface AriaHasTabbableChildOptions {
+  isDisabled?: boolean
+}
+
+// This was created for a special empty case of a component that can have child or
+// be empty, like Collection/Virtualizer/Table/ListView/etc. When these components
+// are empty they can have a message with a tabbable element, which is like them
+// being not empty, when it comes to focus and tab order.
+
+/**
+ * Returns whether an element has a tabbable child, and updates as children change.
+ * @private
+ */
+export function useHasTabbableChild(ref: RefObject<Element | null>, options?: AriaHasTabbableChildOptions): boolean {
+  let isDisabled = options?.isDisabled;
+  let [hasTabbableChild, setHasTabbableChild] = useState(false);
+
+  useLayoutEffect(() => {
+    if (ref?.current && !isDisabled) {
+      let update = () => {
+        if (ref.current) {
+          let walker = getFocusableTreeWalker(ref.current, {tabbable: true});
+          setHasTabbableChild(!!walker.nextNode());
+        }
+      };
+
+      update();
+
+      // Update when new elements are inserted, or the tabIndex/disabled attribute updates.
+      let observer = new MutationObserver(update);
+      observer.observe(ref.current, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: ['tabIndex', 'disabled']
+      });
+
+      return () => {
+        // Disconnect mutation observer when a React update occurs on the top-level component
+        // so we update synchronously after re-rendering. Otherwise React will emit act warnings
+        // in tests since mutation observers fire asynchronously. The mutation observer is necessary
+        // so we also update if a child component re-renders and adds/removes something tabbable.
+        observer.disconnect();
+      };
+    }
+  });
+
+  return isDisabled ? false : hasTabbableChild;
+}