feat(dialog, modal, popover, sheet): add options prop to customize focus-trap #11453

jcfranco · 2025-02-05T07:11:12Z

Related Issue: #11345

Summary

Adds focusTrapOptions option to allow additional customization of focus-trapping components. It supports the following options from https://github.com/focus-trap/focus-trap#createoptions:

initialFocus – would replace popover's internal initialFocusTrapFocus prop
allowOutsideClick – supports Popover - When clicked outside of a focus trap, focus is not returned to the element prior to the focus trap #10682
returnFocusOnDeactivate – supports Popover - When clicked outside of a focus trap, focus is not returned to the element prior to the focus trap #10682

And the following custom prop:

extraContainers – allows specifying extra elements (nodes or selectors) to focus trap (e.g., anything appending to the body, etc) when creating/activating the trap. Note: if specified, elements must exist when the focus trap is activated, if extra containers are created afterwards, users can use updateFocusTrapElements(extraContainers)

This also enhances updatesFocusTrapElements() to accept extra containers to allow in the focus trap if these are created after the trap is activated.

Notes

A subset of https://github.com/focus-trap/focus-trap#createoptions options are exposed as certain configurations might break component functionality.
extraContainers gets used both when creating and updating the focus trap target containers
Tidies up types

…d options to configure focus trap

driskull

Looks good! We'll need to do this for Modal, Popover, and Sheet as well.

driskull · 2025-02-05T16:53:31Z

packages/calcite-components/src/components/dialog/dialog.tsx

@@ -161,6 +161,9 @@ export class Dialog extends LitElement implements OpenCloseComponent, LoadableCo
   */
  @property({ reflect: true }) escapeDisabled = false;

+  /** Allows special focus-trap configuration. */


Maybe Allows for focus trapping configuration?

We'll probably need to document the options as well right? "allowOutsideClick" | "initialFocus" | "returnFocusOnDeactivate"

Totally. @geospatialem @DitwanP Any ideas on how we should doc items from another lib? I don't think we call out using focus-trap or other 3rd-party lib anywhere in the doc site.

Yeah we don't want to call out focus-trap specifically so we can say "focus trapping"

Maybe something like:

Specifies custom focus trap configuration on the component, where `"allowOutsideClick`" allows outside clicks, `"initialFocus"` enables initial focus, and `"returnFocusOnDeactivate"` returns focus when not active.

I'm not 100% sure if that's the true intended behavior for the options, but perhaps something to that effect?

jcfranco · 2025-02-05T17:21:23Z

Looks good! We'll need to do this for Modal, Popover, and Sheet as well.

Got these PRs standing by:

… into jcfranco/11345-add-focus-trap-options

jcfranco · 2025-02-06T00:32:56Z

I'll work on adding automated test coverage for some of these changes and controller-specific testing will be handled in #11305.

driskull

👍

driskull · 2025-02-06T00:34:19Z

packages/calcite-components/src/components/dialog/dialog.tsx

-  async updateFocusTrapElements(): Promise<void> {
-    this.focusTrap.updateContainerElements();
+  async updateFocusTrapElements(
+    extraContainers?: ExtendedFocusTrapOptions["extraContainers"],


nice, this looks good 👍

Elijbet · 2025-02-06T00:51:41Z

packages/calcite-components/src/components/modal/modal.tsx

@@ -81,7 +71,21 @@ export class Modal
    this.updateSizeCssVars();
  });

-  focusTrap: FocusTrap;
+  focusTrap = useFocusTrap<this>({


✨🎮 ✅✨ Nice. Brings all the rest of the components up to date!

Elijbet · 2025-02-06T01:08:02Z

packages/calcite-components/src/controllers/useFocusTrap.ts

+   * @see https://github.com/focus-trap/focus-trap#createoptions
+   */
+  Pick<FocusTrapOptions, "allowOutsideClick" | "initialFocus" | "returnFocusOnDeactivate"> & {
+    /**


How come this doesn't include escapeDeactivates?

I didn't include some options that may conflict with existing component props (e.g., escapeDisabled), but we could revisit this if there's a use case.

Elijbet · 2025-02-06T01:09:36Z

packages/calcite-components/src/components/sheet/sheet.tsx

+   * `"initialFocus"` enables initial focus,
+   * `"returnFocusOnDeactivate"` returns focus when not active, and
+   * `"extraContainers"` specifies additional focusable elements external to the trap (e.g., 3rd-party components appending elements to the document body).
+   */


Shouldn't this include escapeDeactivates?

jcfranco · 2025-02-06T02:57:32Z

Merging to proceed with testing and verification. LMK if anything needs following up.

…cus-trap (#11453) **Related Issue:** #11345 ## Summary Adds `focusTrapOptions` option to allow additional customization of focus-trapping components. It supports the following options from https://github.com/focus-trap/focus-trap#createoptions: * `initialFocus` – would replace popover's internal initialFocusTrapFocus prop * `allowOutsideClick` – supports #10682 * `returnFocusOnDeactivate` – supports #10682 And the following custom prop: * `extraContainers` – allows specifying extra elements (nodes or selectors) to focus trap (e.g., anything appending to the body, etc) when creating/activating the trap. **Note**: if specified, elements must exist when the focus trap is activated, if extra containers are created afterwards, users can use `updateFocusTrapElements(extraContainers)` This also enhances `updatesFocusTrapElements()` to accept extra containers to allow in the focus trap if these are created after the trap is activated. ### Notes * A subset of https://github.com/focus-trap/focus-trap#createoptions options are exposed as certain configurations might break component functionality. * `extraContainers` gets used both when creating and updating the focus trap target containers * Tidies up types

feat(dialog): add options prop to customize focus-trap

3013a4e

github-actions bot assigned jcfranco Feb 5, 2025

github-actions bot added the enhancement Issues tied to a new feature or request. label Feb 5, 2025

jcfranco marked this pull request as draft February 5, 2025 07:20

jcfranco requested review from driskull and Elijbet February 5, 2025 07:20

jcfranco added 3 commits February 4, 2025 23:42

feat(input-date-picker, input-time-picker, modal, popover, sheet): ad…

ee6d923

…d options to configure focus trap

drop focusTrapOptions props

5fe3bac

feat(modal, popover, sheet): add focusTrapOptions prop

a6cf46b

This was referenced Feb 5, 2025

feat(modal, popover, sheet): add focusTrapOptions #11455

Closed

Calcite Dialog prevents interaction of elements when modal attribute is set #11420

Closed

driskull reviewed Feb 5, 2025

View reviewed changes

jcfranco added 6 commits February 5, 2025 12:40

improve focusTrapOptions doc

b9a9a81

allow passing extraContainers to update container elements method

7a58775

Merge branch 'jcfranco/add-focus-trap-props-for-container-components'…

35fae3f

… into jcfranco/11345-add-focus-trap-options

roll back input time/date picker using useFocusTrap controller

08d24cc

update focusTrapOptions doc

ef87d21

update focusTrapElements()

4183632

jcfranco changed the title ~~feat(dialog): add options prop to customize focus-trap~~ feat(dialog, modal, popover, sheet): add options prop to customize focus-trap Feb 6, 2025

merge dev

a85a9c6

jcfranco marked this pull request as ready for review February 6, 2025 00:26

jcfranco requested review from driskull and geospatialem February 6, 2025 00:26

restore input-time-picker disabling of initial focus

ce0e352

jcfranco requested a review from eriklharper February 6, 2025 00:29

driskull approved these changes Feb 6, 2025

View reviewed changes

Elijbet approved these changes Feb 6, 2025

View reviewed changes

jcfranco added the pr ready for visual snapshots Adding this label will run visual snapshot testing. label Feb 6, 2025

jcfranco merged commit 454f8e8 into dev Feb 6, 2025
17 checks passed

jcfranco deleted the jcfranco/11345-add-focus-trap-options branch February 6, 2025 02:57

github-actions bot added this to the 2025-02-06 - 3.0.0 Feb Breaking Change Release milestone Feb 6, 2025

calcite-admin mentioned this pull request Feb 8, 2025

chore: release main #11500

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(dialog, modal, popover, sheet): add options prop to customize focus-trap #11453

feat(dialog, modal, popover, sheet): add options prop to customize focus-trap #11453

jcfranco commented Feb 5, 2025 •

edited

Loading

driskull left a comment

driskull Feb 5, 2025

driskull Feb 5, 2025

jcfranco Feb 5, 2025

driskull Feb 5, 2025

geospatialem Feb 5, 2025

jcfranco commented Feb 5, 2025

jcfranco commented Feb 6, 2025

driskull left a comment

driskull Feb 6, 2025

Elijbet Feb 6, 2025

Elijbet Feb 6, 2025

jcfranco Feb 6, 2025 •

edited

Loading

Elijbet Feb 6, 2025

jcfranco commented Feb 6, 2025

feat(dialog, modal, popover, sheet): add options prop to customize focus-trap #11453

feat(dialog, modal, popover, sheet): add options prop to customize focus-trap #11453

Conversation

jcfranco commented Feb 5, 2025 • edited Loading

Summary

Notes

driskull left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jcfranco commented Feb 5, 2025

jcfranco commented Feb 6, 2025

driskull left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jcfranco Feb 6, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jcfranco commented Feb 6, 2025

jcfranco commented Feb 5, 2025 •

edited

Loading

jcfranco Feb 6, 2025 •

edited

Loading