refactor(modal): DLT-3453 trap focus with v-dt-focustrap directive

[Paulo Reis (paulojreis-dialpad)]

Obligatory GIF (super important!)

🛠️ Type Of Change

• Fix
• Feature
• Performance Improvement
• Refactor

📖 Jira Ticket

DLT-3453

📖 Description

Applies the v-dt-focustrap directive to DtModal for cross-component consistency, completing the DLT-3452 rollout. Part of DLT-3452.

Unlike Banner/Popover/ImageViewer, Modal had no focus-trap code/mixin to migrate. It renders a native <dialog> and calls showModal() (no Modal mixin, no focusTrappedTabPress), so the browser already traps Tab.

tl;dr/key open question:

• We do have the option of not using the directive at all, as the native <dialog> handles focus trapping for us. This PR adds the directive, but we can decide to rely on the native behaviour instead.

⚖️ Trade-off: native <dialog> vs. v-dt-focustrap

Modal is the one component in this rollout where the directive is somewhat redundant.

Capability	Native <dialog>.showModal()	v-dt-focustrap (trap-only, as applied)
Tab boundary trapping	✅ — covers all focusable types	✅ — but a narrower selector (see limitation)
Background made inert — blocks mouse clicks and AT / screen-reader access to the page behind	✅	❌ — only intercepts Tab; does nothing to the background
Focus restoration on close	✅	❌ off here (restoreFocus: false; Modal handles it)
Initial focus on open	✅	❌ off here (initialFocus: false; Modal handles it)
Top layer + ::backdrop + Esc (cancel)	✅	❌ not its concern

What the directive actually adds for Modal:

1. Cross-component consistency — every focus-trapping surface uses one primitive (the explicit DLT-3452 goal). A maintainability/API benefit, not a user-facing capability.
2. A safeguard — if native dialog trapping ever fails to engage (a browser with incomplete <dialog> support, or if showModal() didn't run), the JS trap still contains Tab. Never triggers on evergreen browsers with proper <dialog> support.

Known behavioural difference: Tab containment. Our own focus-trapping mechanism keeps tab navigation confined within the container only; the native <dialog> trapping allows the user to tab away and reach the browser's chrome (e.g. address bar). Videos below illustrate this.

Known limitation: the directive's tabbable selector (button,[href],input,select,textarea,details,[tabindex]) is narrower than the browser's native focus navigation. If a modal's last focusable is an element the selector doesn't match — a contenteditable, <iframe>, or media element with controls — the directive wraps at its last known focusable before reaching it, making that trailing element Tab-unreachable. It stays focusable by click/programmatically, and stays reachable if it's not the trailing element (native handles the middle; the directive only acts at its boundaries). Likelihood is low for Dialtone modals (overwhelmingly buttons/inputs/links), but it's a real subtraction relative to native-only.

💡 Context

Focus trapping was scattered across components via the Modal mixin; DLT-3452 consolidates it on the v-dt-focustrap directive (shipped in #1195). v-dt-focustrap is a globally-installed plugin — used in the template with no local directives: registration; consumer apps already call app.use(DtFocustrapDirective), and Storybook registers it in preview.jsx.

📄 Documentation Artifacts

Artifact	Status	Notes
Vue source	✅ Updated	Modal.vue — directive added (trap-only)
Tests	✅ Updated	Modal.test.js — directive registered + trap test
VuePress docs	✅ Updated	modal-native-dialog guide — Focus management rephrased (behavior-first) + directive note
Storybook stories	➖ n/a	unchanged
Component-docs JSON / MCP data	➖ n/a	no prop/JSDoc change

📝 Checklist

For all PRs:

• I have ensured no private Dialpad links or info are in the code or pull request description (Dialtone is a public repo!).
• I have reviewed my changes.
• I have added all relevant documentation.
• I have considered the performance impact of my change.

For all Vue changes:

• I have added / updated unit tests.
• I have validated components with a screen reader.
• I have validated components keyboard navigation.

📷 Screenshots / GIFs

Current state, notice how the address bar is reachable

Screen.Recording.2026-06-05.at.11.16.31.mov

This PR, notice how tab navigation is contained within the dialog

Screen.Recording.2026-06-05.at.11.17.12.mov

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 0dbe7458-f1d1-48e3-8a5f-5ad7e273b2e8

📥 Commits

Reviewing files that changed from the base of the PR and between a79a90b and add7bb0.

📒 Files selected for processing (2)

• apps/dialtone-documentation/docs/guides/migration/modal-native-dialog/index.md
• packages/dialtone-vue/components/Modal/Modal.test.js

---

Apply v-dt-focustrap to DtModal (trap-only: initialFocus/restoreFocus disabled) to enforce Tab trapping; tests register the directive and assert Tab/Shift+Tab wrapping; migration docs updated to explain native vs directive behavior and Escape handling.

Overall Judgement: ✅ Ready to merge — Focused, well-tested, and documented change with no public API impact and minimal surface area.

Walkthrough

This PR integrates the v-dt-focustrap directive into DtModal's native <dialog> (active when open) without the directive performing initial focus or restore; tests register the directive (including shadow-root mounts) and assert Tab/Shift+Tab wrapping and prevented defaults; docs were updated to describe native dialog focus-wrapping and Escape via the cancel event.

Changes

Focustrap Directive Integration

Layer / File(s)	Summary
Focustrap directive in Modal component packages/dialtone-vue/components/Modal/Modal.vue	The <dialog> element binds v-dt-focustrap configured to activate when the modal is open (active: open) and to disable internal focus initialization and restoration (initialFocus: false, restoreFocus: false).
Test setup and focus-trapping verification packages/dialtone-vue/components/Modal/Modal.test.js	Test suite imports the focustrap directive, getTabbableElements, and flushPromises; registers DtFocustrapDirective in the primary mount config and in shadow-root mount variants; and adds a "Focus trapping" test that renders tabbable buttons and verifies Tab/Shift+Tab wrap behavior with default-prevented keydown events.
Migration guide focus management documentation apps/dialtone-documentation/docs/guides/migration/modal-native-dialog/index.md	TLDR, Focus management bullets, and the checklist now state that native <dialog> opened via showModal() with v-dt-focustrap enforces focus trapping and that Escape closes the modal via the dialog cancel event handled with @cancel.prevent.

Possibly related PRs

• dialpad/dialtone#1313: Also wires up v-dt-focustrap and adjusts focus-trapping tests for a modal-like component (DtImageViewer).

Suggested reviewers

• francisrupert
• iropolo
• braddialpad
• ninarepetto

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/DLT-3453-modal-focustrap

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

apps/dialtone-documentation/docs/guides/migration/modal-native-dialog/index.md (1)

9-9: 🧹 Nitpick | 🔵 Trivial

Advisory: Linked repositories have an existing focus-trap directive.

Based on linked repositories context, dialpad/firespotter contains an existing @dialpad/focus-trap-directive implementation and multiple DtModal consumers. When this change ships, ensure consumers using both the old focus-trap directive and the new v-dt-focustrap-equipped DtModal don't encounter conflicts (e.g., double Tab handling, competing keydown listeners). The firespotter modal store and keyboard handlers may also need review for assumptions about Tab/Escape behavior.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@apps/dialtone-documentation/docs/guides/migration/modal-native-dialog/index.md`
at line 9, Consumers may experience focus/keyboard conflicts when the new
v-dt-focustrap-enabled DtModal is used alongside the existing
`@dialpad/focus-trap-directive` and firespotter modal handlers; audit and
reconcile focus handling by locating usages of DtModal and v-dt-focustrap and
replacing or namespacing duplicate focus-trap directives, remove or guard
redundant keydown/tab handlers in the firespotter modal store and any
`@dialpad/focus-trap-directive` instantiations, and ensure only one focus-trap
handles Tab/Escape (or coordinate event propagation) so Tab cycling and Escape
closing behave predictably across consumers.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/dialtone-vue/components/Modal/Modal.test.js`:
- Around line 204-230: Add a symmetric test in Modal.test.js under the "Focus
trapping" describe block mirroring the existing Tab test: after flushPromises(),
build focusables from overlay.element (same query), grab first and last, set
focus on first, dispatch a KeyboardEvent('keydown', { key: 'Tab', shiftKey:
true, bubbles: true, cancelable: true }) on overlay.element, and assert the
event.defaultPrevented is true and document.activeElement is last; reference
existing identifiers overlay, focusables, first, last, and the
KeyboardEvent('keydown') usage so the new test follows the same pattern as the
forward-Tab spec.

---

Outside diff comments:
In
`@apps/dialtone-documentation/docs/guides/migration/modal-native-dialog/index.md`:
- Line 9: Consumers may experience focus/keyboard conflicts when the new
v-dt-focustrap-enabled DtModal is used alongside the existing
`@dialpad/focus-trap-directive` and firespotter modal handlers; audit and
reconcile focus handling by locating usages of DtModal and v-dt-focustrap and
replacing or namespacing duplicate focus-trap directives, remove or guard
redundant keydown/tab handlers in the firespotter modal store and any
`@dialpad/focus-trap-directive` instantiations, and ensure only one focus-trap
handles Tab/Escape (or coordinate event propagation) so Tab cycling and Escape
closing behave predictably across consumers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: c9804cf9-1b31-4672-a72c-a2dce4608a8e

📥 Commits

Reviewing files that changed from the base of the PR and between aec9acf and aa4aaef.

⛔ Files ignored due to path filters (1)

• apps/dialtone-documentation/docs/.vuepress/public/assets/images/components/modal-dark.png is excluded by !**/*.png and included by **

📒 Files selected for processing (3)

• apps/dialtone-documentation/docs/guides/migration/modal-native-dialog/index.md
• packages/dialtone-vue/components/Modal/Modal.test.js
• packages/dialtone-vue/components/Modal/Modal.vue

[Belu Montoya (belumontoya)]

same as the other ones

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@apps/dialtone-documentation/docs/guides/migration/modal-native-dialog/index.md`:
- Around line 67-68: Update the TLDR/checklist wording so it matches the
detailed explanation: state that focus trapping and Escape-to-close are
automatic only when using the native <dialog> opened with showModal() together
with the v-dt-focustrap directive, and that DtModal listens for the native
cancel event via `@cancel.prevent` to close; replace any blanket "native-only"
phrasing on the TLDR lines (currently around lines referencing the checklist)
with this precise message so it no longer contradicts the detailed section that
mentions <dialog>, showModal(), v-dt-focustrap and DtModal.

In `@packages/dialtone-vue/components/Modal/Modal.test.js`:
- Around line 213-229: The test "keeps focus trapped inside the open dialog (Tab
wraps from last to first)" is querying bare tags for tabbable elements, making
it brittle; change the selector logic in the test (the focusables variable
creation that uses
overlay.element.querySelectorAll('button,[href],input,select,textarea,details,[tabindex]'))
to select explicit data-qa attributes instead (e.g.
overlay.element.querySelectorAll('[data-qa="modal-focusable"]') or your
project's standard data-qa name), and ensure the test fixture markup provides
those data-qa attributes so first/last focusable resolution and the Tab key
dispatch/assertions (including checking tabEvent.defaultPrevented and
document.activeElement) continue to work unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 0af724db-557d-4328-a889-5058a5c5af8e

📥 Commits

Reviewing files that changed from the base of the PR and between aa4aaef and a79a90b.

⛔ Files ignored due to path filters (1)

• apps/dialtone-documentation/docs/.vuepress/public/assets/images/components/modal-dark.png is excluded by !**/*.png and included by **

📒 Files selected for processing (3)

• apps/dialtone-documentation/docs/guides/migration/modal-native-dialog/index.md
• packages/dialtone-vue/components/Modal/Modal.test.js
• packages/dialtone-vue/components/Modal/Modal.vue

[github-actions]

Please add either the visual-test-ready or no-visual-test label to this PR depending on whether you want to run visual tests or not.
It is recommended to run visual tests if your PR changes any UI. ‼️

[github-actions]

✔️ Deploy previews ready!
😎 Dialtone documentation preview: https://dialtone.dialpad.com/deploy-previews/pr-1316/
😎 Dialtone-vue preview: https://dialtone.dialpad.com/vue/deploy-previews/pr-1316/