docs: add focus restoration to our examples, and update the docs to reflect authoring requirements (microsoft#33924)

Author: smhigley

packages/react-components/react-drawer/stories/src/Drawer/DrawerBestPractices.md

@@ -10,7 +10,8 @@
 
 ### Accessibility
 
+**Focus**: If the Drawer has a trigger and can be closed, use the `useRestoreFocusTarget` and `useRestoreFocusSource` hooks to handle focus restoration as shown in our examples. Additionally, the `InlineDrawer` does not take focus by default when it is opened; if this functionality is needed, it should be handled manually.
+
 - `OverlayDrawer`: <br>Please refer to the Dialog component to understand the accessibility recommendations and implications.
 - `InlineDrawer`: <br>
   **Semantics**: Renders a plain div and do not imply any accessibility semantics by default. It accepts all aria attributes and it should be customized depending on its context within a page. Consider using `role="region"` for large page-level drawers. <br><br>
-  **Focus**: If the `InlineDrawer` has a trigger and can be closed, use the `useRestoreFocusTarget` and `useRestoreFocusSource` hooks to handle focus restoration as shown in our Default and Inline examples. Additionally, the `InlineDrawer` does not take focus by default when it is opened; if this functionality is needed, it should be handled manually.

packages/react-components/react-drawer/stories/src/Drawer/DrawerCustomSize.stories.tsx

@@ -9,6 +9,8 @@ import {
   tokens,
   makeStyles,
   Input,
+  useRestoreFocusSource,
+  useRestoreFocusTarget,
 } from '@fluentui/react-components';
 import { Dismiss24Regular } from '@fluentui/react-icons';
 
@@ -31,9 +33,15 @@ export const CustomSize = () => {
   const [open, setOpen] = React.useState(false);
   const [customSize, setCustomSize] = React.useState(600);
 
+  // all Drawers need manual focus restoration attributes
+  // unless (as in the case of some inline drawers, you do not want automatic focus restoration)
+  const restoreFocusTargetAttributes = useRestoreFocusTarget();
+  const restoreFocusSourceAttributes = useRestoreFocusSource();
+
   return (
     <div>
       <OverlayDrawer
+        {...restoreFocusSourceAttributes}
         open={open}
         position="end"
         onOpenChange={(_, state) => setOpen(state.open)}
@@ -60,7 +68,7 @@ export const CustomSize = () => {
       </OverlayDrawer>
 
       <div className={styles.main}>
-        <Button appearance="primary" onClick={() => setOpen(true)}>
+        <Button {...restoreFocusTargetAttributes} appearance="primary" onClick={() => setOpen(true)}>
           Open Drawer
         </Button>
 

packages/react-components/react-drawer/stories/src/Drawer/DrawerDefault.stories.tsx

@@ -54,7 +54,8 @@ export const Default = () => {
   const [isOpen, setIsOpen] = React.useState(false);
   const [type, setType] = React.useState<DrawerType>('overlay');
 
-  // Overlay Drawer will handle focus by default, but inline Drawers need manual focus restoration attributes, if applicable
+  // all Drawers need manual focus restoration attributes
+  // unless (as in the case of some inline drawers, you do not want automatic focus restoration)
   const restoreFocusTargetAttributes = useRestoreFocusTarget();
   const restoreFocusSourceAttributes = useRestoreFocusSource();
 

packages/react-components/react-drawer/stories/src/Drawer/DrawerMotionDisabled.stories.tsx

@@ -12,6 +12,8 @@ import {
   makeStyles,
   tokens,
   useId,
+  useRestoreFocusSource,
+  useRestoreFocusTarget,
 } from '@fluentui/react-components';
 import { Dismiss24Regular } from '@fluentui/react-icons';
 
@@ -51,12 +53,18 @@ export const MotionDisabled = () => {
   const [isOpen, setIsOpen] = React.useState(false);
   const [type, setType] = React.useState<DrawerType>('overlay');
 
+  // all Drawers need manual focus restoration attributes
+  // unless (as in the case of some inline drawers, you do not want automatic focus restoration)
+  const restoreFocusTargetAttributes = useRestoreFocusTarget();
+  const restoreFocusSourceAttributes = useRestoreFocusSource();
+
   return (
     <div className={styles.root}>
       <Drawer
         backdropMotion={null}
         surfaceMotion={null}
         type={type}
+        {...restoreFocusSourceAttributes}
         separator
         open={isOpen}
         onOpenChange={(_, { open }) => setIsOpen(open)}
@@ -82,7 +90,7 @@ export const MotionDisabled = () => {
       </Drawer>
 
       <div className={styles.content}>
-        <Button appearance="primary" onClick={() => setIsOpen(!isOpen)}>
+        <Button {...restoreFocusTargetAttributes} appearance="primary" onClick={() => setIsOpen(!isOpen)}>
           {type === 'inline' ? 'Toggle' : 'Open'}
         </Button>
 

packages/react-components/react-drawer/stories/src/Drawer/DrawerMultipleLevels.stories.tsx

@@ -13,6 +13,8 @@ import {
   ToolbarGroup,
   ToolbarButton,
   makeStyles,
+  useRestoreFocusSource,
+  useRestoreFocusTarget,
 } from '@fluentui/react-components';
 import { Dismiss24Regular, Calendar24Regular, Settings24Regular, ArrowLeft24Regular } from '@fluentui/react-icons';
 
@@ -96,9 +98,19 @@ export const MultipleLevels = () => {
   const [isOpen, setIsOpen] = React.useState(false);
   const [level, setLevel] = React.useState<1 | 2>(1);
 
+  // all Drawers need manual focus restoration attributes
+  // unless (as in the case of some inline drawers, you do not want automatic focus restoration)
+  const restoreFocusTargetAttributes = useRestoreFocusTarget();
+  const restoreFocusSourceAttributes = useRestoreFocusSource();
+
   return (
     <div>
-      <OverlayDrawer position="start" open={isOpen} onOpenChange={(_, { open }) => setIsOpen(open)}>
+      <OverlayDrawer
+        {...restoreFocusSourceAttributes}
+        position="start"
+        open={isOpen}
+        onOpenChange={(_, { open }) => setIsOpen(open)}
+      >
         <DrawerHeader>
           <DrawerHeaderNavigation>
             <Toolbar className={styles.toolbar}>
@@ -161,7 +173,7 @@ export const MultipleLevels = () => {
         </DrawerFooter>
       </OverlayDrawer>
 
-      <Button appearance="primary" onClick={() => setIsOpen(true)}>
+      <Button {...restoreFocusTargetAttributes} appearance="primary" onClick={() => setIsOpen(true)}>
         Open Drawer
       </Button>
     </div>

packages/react-components/react-drawer/stories/src/Drawer/DrawerPosition.stories.tsx

@@ -8,6 +8,8 @@ import {
   Button,
   makeStyles,
   tokens,
+  useRestoreFocusSource,
+  useRestoreFocusTarget,
 } from '@fluentui/react-components';
 import { Dismiss24Regular } from '@fluentui/react-icons';
 
@@ -43,9 +45,19 @@ export const Position = () => {
     setIsOpen(true);
   }, []);
 
+  // all Drawers need manual focus restoration attributes
+  // unless (as in the case of some inline drawers, you do not want automatic focus restoration)
+  const restoreFocusTargetAttributes = useRestoreFocusTarget();
+  const restoreFocusSourceAttributes = useRestoreFocusSource();
+
   return (
     <div>
-      <OverlayDrawer position={position} open={isOpen} onOpenChange={(_, { open }) => setIsOpen(open)}>
+      <OverlayDrawer
+        position={position}
+        {...restoreFocusSourceAttributes}
+        open={isOpen}
+        onOpenChange={(_, { open }) => setIsOpen(open)}
+      >
         <DrawerHeader>
           <DrawerHeaderTitle
             action={
@@ -67,15 +79,15 @@ export const Position = () => {
       </OverlayDrawer>
 
       <div className={styles.content}>
-        <Button appearance="primary" onClick={onClickStartButton}>
+        <Button {...restoreFocusTargetAttributes} appearance="primary" onClick={onClickStartButton}>
           Open start
         </Button>
 
-        <Button appearance="primary" onClick={onClickEndButton}>
+        <Button {...restoreFocusTargetAttributes} appearance="primary" onClick={onClickEndButton}>
           Open end
         </Button>
 
-        <Button appearance="primary" onClick={onClickBottomButton}>
+        <Button {...restoreFocusTargetAttributes} appearance="primary" onClick={onClickBottomButton}>
           Open Bottom
         </Button>
       </div>

packages/react-components/react-drawer/stories/src/Drawer/DrawerPreventClose.stories.tsx

@@ -1,13 +1,26 @@
 import * as React from 'react';
-import { OverlayDrawer, DrawerBody, DrawerHeader, DrawerHeaderTitle, Button } from '@fluentui/react-components';
+import {
+  OverlayDrawer,
+  DrawerBody,
+  DrawerHeader,
+  DrawerHeaderTitle,
+  Button,
+  useRestoreFocusSource,
+  useRestoreFocusTarget,
+} from '@fluentui/react-components';
 import { Dismiss24Regular } from '@fluentui/react-icons';
 
 export const PreventClose = () => {
   const [open, setOpen] = React.useState(false);
 
+  // all Drawers need manual focus restoration attributes
+  // unless (as in the case of some inline drawers, you do not want automatic focus restoration)
+  const restoreFocusTargetAttributes = useRestoreFocusTarget();
+  const restoreFocusSourceAttributes = useRestoreFocusSource();
+
   return (
     <div>
-      <OverlayDrawer position="end" open={open} modalType="alert">
+      <OverlayDrawer {...restoreFocusSourceAttributes} position="end" open={open} modalType="alert">
         <DrawerHeader>
           <DrawerHeaderTitle
             action={
@@ -28,7 +41,7 @@ export const PreventClose = () => {
         </DrawerBody>
       </OverlayDrawer>
 
-      <Button appearance="primary" onClick={() => setOpen(true)}>
+      <Button {...restoreFocusTargetAttributes} appearance="primary" onClick={() => setOpen(true)}>
         Open Drawer
       </Button>
     </div>

packages/react-components/react-drawer/stories/src/Drawer/DrawerResponsive.stories.tsx

@@ -8,6 +8,8 @@ import {
   Button,
   makeStyles,
   tokens,
+  useRestoreFocusSource,
+  useRestoreFocusTarget,
 } from '@fluentui/react-components';
 import { Dismiss24Regular } from '@fluentui/react-icons';
 
@@ -51,9 +53,21 @@ export const Responsive = () => {
     return () => match.removeEventListener('change', onMediaQueryChange);
   }, [onMediaQueryChange]);
 
+  // all Drawers need manual focus restoration attributes
+  // unless (as in the case of some inline drawers, you do not want automatic focus restoration)
+  const restoreFocusTargetAttributes = useRestoreFocusTarget();
+  const restoreFocusSourceAttributes = useRestoreFocusSource();
+
   return (
     <div className={styles.root}>
-      <Drawer type={type} separator position="start" open={isOpen} onOpenChange={(_, { open }) => setIsOpen(open)}>
+      <Drawer
+        type={type}
+        {...restoreFocusSourceAttributes}
+        separator
+        position="start"
+        open={isOpen}
+        onOpenChange={(_, { open }) => setIsOpen(open)}
+      >
         <DrawerHeader>
           <DrawerHeaderTitle
             action={
@@ -75,7 +89,7 @@ export const Responsive = () => {
       </Drawer>
 
       <div className={styles.content}>
-        <Button appearance="primary" onClick={() => setIsOpen(!isOpen)}>
+        <Button {...restoreFocusTargetAttributes} appearance="primary" onClick={() => setIsOpen(!isOpen)}>
           Toggle
         </Button>
 

packages/react-components/react-drawer/stories/src/Drawer/DrawerSize.stories.tsx

@@ -12,6 +12,8 @@ import {
   useId,
   tokens,
   makeStyles,
+  useRestoreFocusSource,
+  useRestoreFocusTarget,
 } from '@fluentui/react-components';
 import { Dismiss24Regular } from '@fluentui/react-icons';
 
@@ -44,9 +46,20 @@ export const Size = () => {
     full: 'Full',
   };
 
+  // all Drawers need manual focus restoration attributes
+  // unless (as in the case of some inline drawers, you do not want automatic focus restoration)
+  const restoreFocusTargetAttributes = useRestoreFocusTarget();
+  const restoreFocusSourceAttributes = useRestoreFocusSource();
+
   return (
     <div>
-      <OverlayDrawer size={size} position="end" open={open} onOpenChange={(_, state) => setOpen(state.open)}>
+      <OverlayDrawer
+        size={size}
+        {...restoreFocusSourceAttributes}
+        position="end"
+        open={open}
+        onOpenChange={(_, state) => setOpen(state.open)}
+      >
         <DrawerHeader>
           <DrawerHeaderTitle
             action={
@@ -68,7 +81,7 @@ export const Size = () => {
       </OverlayDrawer>
 
       <div className={styles.main}>
-        <Button appearance="primary" onClick={() => setOpen(true)}>
+        <Button {...restoreFocusTargetAttributes} appearance="primary" onClick={() => setOpen(true)}>
           Open Drawer
         </Button>
 

packages/react-components/react-drawer/stories/src/Drawer/DrawerWithNavigation.stories.tsx

@@ -10,6 +10,8 @@ import {
   ToolbarGroup,
   ToolbarButton,
   makeStyles,
+  useRestoreFocusSource,
+  useRestoreFocusTarget,
 } from '@fluentui/react-components';
 import {
   Dismiss24Regular,
@@ -30,9 +32,19 @@ export const WithNavigation = () => {
 
   const [isOpen, setIsOpen] = React.useState(false);
 
+  // all Drawers need manual focus restoration attributes
+  // unless (as in the case of some inline drawers, you do not want automatic focus restoration)
+  const restoreFocusTargetAttributes = useRestoreFocusTarget();
+  const restoreFocusSourceAttributes = useRestoreFocusSource();
+
   return (
     <div>
-      <OverlayDrawer position="start" open={isOpen} onOpenChange={(_, { open }) => setIsOpen(open)}>
+      <OverlayDrawer
+        position="start"
+        {...restoreFocusSourceAttributes}
+        open={isOpen}
+        onOpenChange={(_, { open }) => setIsOpen(open)}
+      >
         <DrawerHeader>
           <DrawerHeaderNavigation className={styles.header}>
             <Button aria-label="Back" appearance="subtle" icon={<ArrowLeft24Regular />} />
@@ -58,7 +70,7 @@ export const WithNavigation = () => {
         </DrawerBody>
       </OverlayDrawer>
 
-      <Button appearance="primary" onClick={() => setIsOpen(true)}>
+      <Button {...restoreFocusTargetAttributes} appearance="primary" onClick={() => setIsOpen(true)}>
         Open Drawer
       </Button>
     </div>