fix Popover focus (#1602)

Fixed focus behavior by changing props in `FloatingFocusManager` and adding `FloatingPortal`; also added fallback `id`/`aria-labelledby` to ensure the dialog is always labelled when it receives focus. Correct behavior described in Accessibility section of docs.

Also adjusted some props.

apps/storybook/src/Table.stories.tsx

@@ -2195,27 +2195,31 @@ export const CustomFilter = () => {
             handleChange(value === 'on', '3');
           }}
           checked={filter === '3'}
+          autoFocus={filter === '3'} // moving focus to checked radio button when filter dialog opens
         />
         <Radio
           label="Contains '5'"
           onChange={({ target: { value } }) => {
             handleChange(value === 'on', '5');
           }}
           checked={filter === '5'}
+          autoFocus={filter === '5'}
         />
         <Radio
           label="Contains '7'"
           onChange={({ target: { value } }) => {
             handleChange(value === 'on', '7');
           }}
           checked={filter === '7'}
+          autoFocus={filter === '7'}
         />
         <Radio
           label='No filter'
           onChange={({ target: { value } }) => {
             handleChange(value === 'on', '');
           }}
           checked={filter === ''}
+          autoFocus={filter === ''}
         />
       </BaseFilter>
     );

packages/itwinui-react/src/core/DropdownMenu/DropdownMenu.tsx

@@ -16,7 +16,7 @@ import type {
   PortalProps,
 } from '../utils/index.js';
 import { Menu } from '../Menu/Menu.js';
-import { Popover, usePopover } from '../Popover/Popover.js';
+import { usePopover } from '../Popover/Popover.js';
 
 export type DropdownMenuProps = {
   /**
@@ -37,7 +37,7 @@ export type DropdownMenuProps = {
    */
   children: React.ReactNode;
 } & Pick<
-  React.ComponentProps<typeof Popover>,
+  Parameters<typeof usePopover>[0],
   'visible' | 'onVisibleChange' | 'placement' | 'matchWidth'
 > &
   React.ComponentPropsWithoutRef<'ul'> &

packages/itwinui-react/src/core/Popover/Popover.tsx

@@ -23,12 +23,14 @@ import {
   useFocus,
   safePolygon,
   useRole,
+  FloatingPortal,
 } from '@floating-ui/react';
 import type { SizeOptions, Placement } from '@floating-ui/react';
 import {
   Box,
   cloneElementWithRef,
   useControlledState,
+  useId,
   useMergedRefs,
 } from '../utils/index.js';
 import type { PolymorphicForwardRefComponent } from '../utils/index.js';
@@ -54,12 +56,10 @@ type PopoverOptions = {
   onVisibleChange?: (visible: boolean) => void;
   /**
    * If true, the popover will close when clicking outside it.
+   *
+   * @default true
    */
   closeOnOutsideClick?: boolean;
-  /**
-   * Whether the popover should match the width of the trigger.
-   */
-  matchWidth?: boolean;
 };
 
 // keep public api small to start with
@@ -101,6 +101,10 @@ type PopoverInternalProps = {
    */
   trigger?: Partial<Record<'hover' | 'click' | 'focus', boolean>>;
   role?: 'dialog' | 'menu' | 'listbox';
+  /**
+   * Whether the popover should match the width of the trigger.
+   */
+  matchWidth?: boolean;
 };
 
 // ----------------------------------------------------------------------------
@@ -193,32 +197,49 @@ export const usePopover = (options: PopoverOptions & PopoverInternalProps) => {
 // ----------------------------------------------------------------------------
 
 type PopoverPublicProps = {
+  /**
+   * Content displayed inside the popover.
+   */
   content?: React.ReactNode;
+  /**
+   * Element that triggers the popover. Should usually be a button.
+   */
   children?: React.ReactNode;
+  /**
+   * Whether the popover adds recommended CSS (background-color, box-shadow, etc.) to itself.
+   *
+   * @default false
+   */
   applyBackground?: boolean;
 } & PortalProps &
   PopoverOptions;
 
 /**
- * A utility component to help with positioning of floating content.
- * Built on top of [`floating-ui`](https://floating-ui.com/)
+ * A utility component to help with positioning of floating content relative to a trigger.
+ * Built on top of [`floating-ui`](https://floating-ui.com/).
+ *
+ * @see https://itwinui.bentley.com/docs/popover
+ *
+ * @example
+ * <Popover content='This is a popover'>
+ *   <Button>Show popover</Button>
+ * </Popover>
  */
 export const Popover = React.forwardRef((props, forwardedRef) => {
   const {
     portal = true,
     //
     // popover options
     visible,
-    placement,
+    placement = 'bottom-start',
     onVisibleChange,
-    closeOnOutsideClick,
-    matchWidth,
+    closeOnOutsideClick = true,
     //
     // dom props
     className,
     children,
     content,
-    applyBackground,
+    applyBackground = false,
     ...rest
   } = props;
 
@@ -227,7 +248,6 @@ export const Popover = React.forwardRef((props, forwardedRef) => {
     placement,
     onVisibleChange,
     closeOnOutsideClick,
-    matchWidth,
     role: 'dialog',
   });
 
@@ -239,36 +259,46 @@ export const Popover = React.forwardRef((props, forwardedRef) => {
     setPopoverElement,
   );
 
+  const triggerId = `${useId()}-trigger`;
+  const hasAriaLabel = !!props['aria-labelledby'] || !!props['aria-label'];
+
   return (
     <>
       {cloneElementWithRef(children, (children) => ({
+        id: children.props.id || triggerId,
         ...popover.getReferenceProps(children.props),
         ref: popover.refs.setReference,
       }))}
 
       {popover.open ? (
         <Portal portal={portal}>
-          <ThemeProvider
-            portalContainer={popoverElement} // portal nested popovers into this one
-          >
-            <FloatingFocusManager
-              context={popover.context}
-              modal={false}
-              initialFocus={-1}
-              returnFocus
+          <FloatingPortal>
+            <ThemeProvider
+              portalContainer={popoverElement} // portal nested popovers into this one
             >
-              <Box
-                className={cx(
-                  { 'iui-popover-surface': applyBackground },
-                  className,
-                )}
-                {...popover.getFloatingProps(rest)}
-                ref={popoverRef}
+              <FloatingFocusManager
+                context={popover.context}
+                modal={false}
+                initialFocus={popover.refs.floating}
               >
-                {content}
-              </Box>
-            </FloatingFocusManager>
-          </ThemeProvider>
+                <Box
+                  className={cx(
+                    { 'iui-popover-surface': applyBackground },
+                    className,
+                  )}
+                  aria-labelledby={
+                    !hasAriaLabel
+                      ? popover.refs.domReference.current?.id
+                      : undefined
+                  }
+                  {...popover.getFloatingProps(rest)}
+                  ref={popoverRef}
+                >
+                  {content}
+                </Box>
+              </FloatingFocusManager>
+            </ThemeProvider>
+          </FloatingPortal>
         </Portal>
       ) : null}
     </>