Merge pull request #2508 from hashicorp/modal-flyout-return-focus-to-…

…docs `Modal`/` Flyout` - Add `returnFocusTo` documentation
hashicorp · Oct 21, 2024 · c78be54 · c78be54
2 parents 4110bd8 + 91ff1d1
commit c78be54
Show file tree

Hide file tree

Showing 4 changed files with 16 additions and 0 deletions.
diff --git a/website/docs/components/flyout/partials/code/component-api.md b/website/docs/components/flyout/partials/code/component-api.md
@@ -18,6 +18,9 @@
   <C.Property @name="size" @type="enum" @values={{array "medium" "large" }} @default="medium">
     Sets the width of the Flyout.
   </C.Property>
+  <C.Property @name="returnFocusTo" @type="string">
+    The `id` of the element where the focus should be returned once the flyout is closed (e.g., if the element that initiated the event is not in the DOM anymore once closed).
+  </C.Property>
   <C.Property @name="onOpen" @type="function">
     Callback function invoked when the Flyout is opened.
   </C.Property>

diff --git a/website/docs/components/flyout/partials/code/how-to-use.md b/website/docs/components/flyout/partials/code/how-to-use.md
@@ -14,6 +14,14 @@ As an overlaying component, the `Hds::Flyout` is rendered on the [top layer](htt
 
 This component uses [`ember-focus-trap`](https://github.com/josemarluedke/ember-focus-trap) to prevent the focus from going outside the Flyout and to deactivate the Flyout when clicking outside. This Ember modifier requires at least one interactive element to be present within the Flyout, which is by default achieved by the dismiss button in the header.
 
+## Focus and focus trap
+
+This component uses [`ember-focus-trap`](https://github.com/josemarluedke/ember-focus-trap) to prevent the focus from going outside the Flyout and to dismiss the Flyout when clicking outside the Flyout. This Ember modifier requires at least one interactive element to be present within the Modal, which is by default achieved by the dismiss button in the header.
+
+When a Modal is opened with the keyboard, the focus is automatically set to the first focusable element inside the Modal, which is the “Dismiss” button. The action of this button has no effect on the system, so focusing on it helps prevent users from accidentally confirming the Modal.
+
+When the Flyout has been closed, the browser automatically returns the focus to the element that initiated the opening. If that element doesn't exist anymore in the DOM (e.g., if the Flyout is opened using an Interaction item in a Dropdown) the focus is returned to the `<body>` element. To avoid this side-effect (that comes with accessibility implications), it's possible to use the `@returnFocusTo` argument, where the consumer can provide the DOM `id` attribute of the element where the focus should be returned once the Flyout is closed.
+
 ## How to use this component
 
 ```handlebars

diff --git a/website/docs/components/modal/partials/code/component-api.md b/website/docs/components/modal/partials/code/component-api.md
@@ -18,6 +18,9 @@
   <C.Property @name="color" @type="enum" @values={{array "neutral" "warning" "critical" }} @default="neutral">
     Sets the color scheme for the Modal Header elements: icon, tagline, and title.
   </C.Property>
+  <C.Property @name="returnFocusTo" @type="string">
+    The `id` of the element where the focus should be returned once the modal is closed (e.g., if the element that initiated the event is not in the DOM anymore once closed).
+  </C.Property>
   <C.Property @name="onOpen" @type="function">
     Callback function invoked when the Modal is opened.
   </C.Property>

diff --git a/website/docs/components/modal/partials/code/how-to-use.md b/website/docs/components/modal/partials/code/how-to-use.md
@@ -16,6 +16,8 @@ This component uses [`ember-focus-trap`](https://github.com/josemarluedke/ember-
 
 When a Modal is opened with the keyboard, the focus is automatically set to the first focusable element inside the Modal, which is the “Dismiss” button. The action of this button has no effect on the system, so focusing on it helps prevent users from accidentally confirming the Modal.
 
+When the Modal has been closed, the browser automatically returns the focus to the element that initiated the opening. If that element doesn't exist anymore in the DOM (e.g., if the Modal is opened using an Interaction item in a Dropdown) the focus is returned to the `<body>` element. To avoid this side-effect (that comes with accessibility implications), it's possible to use the `@returnFocusTo` argument, where the consumer can provide the DOM `id` attribute of the element where the focus should be returned once the Modal is closed.
+
 ## How to use this component
 
 ```handlebars