From bc9097f704146376d9d8edb1d8377a02293b033a Mon Sep 17 00:00:00 2001
From: Sarah Higley <sarah.higley@microsoft.com>
Date: Mon, 24 Jun 2024 13:50:31 -0700
Subject: [PATCH 1/4] feat: update useModalAttributes to use legacyTrapFocus by
 default

---
 .../src/components/DatePicker/useDatePicker.tsx        |  2 +-
 .../react-tabster/src/hooks/useModalAttributes.ts      | 10 ++++------
 2 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/packages/react-components/react-datepicker-compat/library/src/components/DatePicker/useDatePicker.tsx b/packages/react-components/react-datepicker-compat/library/src/components/DatePicker/useDatePicker.tsx
index f04f8873f3623..8ac6ece0fa2f4 100644
--- a/packages/react-components/react-datepicker-compat/library/src/components/DatePicker/useDatePicker.tsx
+++ b/packages/react-components/react-datepicker-compat/library/src/components/DatePicker/useDatePicker.tsx
@@ -419,7 +419,7 @@ export const useDatePicker_unstable = (props: DatePickerProps, ref: React.Ref<HT
   root.onFocus = useEventCallback(mergeCallbacks(root.onFocus, onInputFocus));
   root.onClick = useEventCallback(mergeCallbacks(root.onClick, onInputClick));
 
-  const { modalAttributes } = useModalAttributes({ trapFocus: true, alwaysFocusable: true, legacyTrapFocus: false });
+  const { modalAttributes } = useModalAttributes({ trapFocus: true, alwaysFocusable: true, legacyTrapFocus: true });
   const popupSurface = open
     ? slot.optional(props.popupSurface, {
         renderByDefault: true,
diff --git a/packages/react-components/react-tabster/src/hooks/useModalAttributes.ts b/packages/react-components/react-tabster/src/hooks/useModalAttributes.ts
index 8d657bb3aa30d..42b52d7ac0a53 100644
--- a/packages/react-components/react-tabster/src/hooks/useModalAttributes.ts
+++ b/packages/react-components/react-tabster/src/hooks/useModalAttributes.ts
@@ -6,17 +6,15 @@ import { useTabster } from './useTabster';
 export interface UseModalAttributesOptions {
   /**
    * Traps focus inside the elements the attributes are applied.
-   * Prefer this to `legacyTrapFocus`
    * it forbids users to tab out of the focus trap into the actual browser.
    */
   trapFocus?: boolean;
 
   /**
    * Traps focus inside the elements the attributes are applied.
-   * This prop enables legacy behavior to match previous versions of Fluent and is not
-   * recommended for general use.
-   * Enabling `legacyTrapFocus` prevents users from tabbing out of the focus trap and into
-   * the actual browser. Prefer using `trapFocus` instead of this prop.
+   * This prop enables traditional force-focus behavior to match previous versions of Fluent
+   * Setting `legacyTrapFocus` to false allows users to tab out of the focus trap and into
+   * the actual browser. This matches the behavior of the native <dialog> element and inert.
    */
   legacyTrapFocus?: boolean;
 
@@ -41,7 +39,7 @@ export interface UseModalAttributesOptions {
 export const useModalAttributes = (
   options: UseModalAttributesOptions = {},
 ): { modalAttributes: TabsterTypes.TabsterDOMAttribute; triggerAttributes: TabsterTypes.TabsterDOMAttribute } => {
-  const { trapFocus, alwaysFocusable, legacyTrapFocus } = options;
+  const { trapFocus, alwaysFocusable, legacyTrapFocus = true } = options;
   const tabster = useTabster();
   // Initializes the modalizer and restorer APIs
   if (tabster) {

From 4f40beb856f09a9a0ef9af6b04960e08df286632 Mon Sep 17 00:00:00 2001
From: Sarah Higley <sarah.higley@microsoft.com>
Date: Mon, 24 Jun 2024 13:52:41 -0700
Subject: [PATCH 2/4] change files

---
 ...picker-compat-bc4d1aaa-945e-4107-9a30-34bbb9550319.json | 7 +++++++
 ...react-tabster-11eb3b52-85dd-4590-9d26-35b95e3112c6.json | 7 +++++++
 2 files changed, 14 insertions(+)
 create mode 100644 change/@fluentui-react-datepicker-compat-bc4d1aaa-945e-4107-9a30-34bbb9550319.json
 create mode 100644 change/@fluentui-react-tabster-11eb3b52-85dd-4590-9d26-35b95e3112c6.json

diff --git a/change/@fluentui-react-datepicker-compat-bc4d1aaa-945e-4107-9a30-34bbb9550319.json b/change/@fluentui-react-datepicker-compat-bc4d1aaa-945e-4107-9a30-34bbb9550319.json
new file mode 100644
index 0000000000000..0f1545d15754e
--- /dev/null
+++ b/change/@fluentui-react-datepicker-compat-bc4d1aaa-945e-4107-9a30-34bbb9550319.json
@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat: update DatePicker to use legacyTrapFocus",
+  "packageName": "@fluentui/react-datepicker-compat",
+  "email": "sarah.higley@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/change/@fluentui-react-tabster-11eb3b52-85dd-4590-9d26-35b95e3112c6.json b/change/@fluentui-react-tabster-11eb3b52-85dd-4590-9d26-35b95e3112c6.json
new file mode 100644
index 0000000000000..82cf6d390f151
--- /dev/null
+++ b/change/@fluentui-react-tabster-11eb3b52-85dd-4590-9d26-35b95e3112c6.json
@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: update useModalAttributes to use legacyTrapFocus by default",
+  "packageName": "@fluentui/react-tabster",
+  "email": "sarah.higley@microsoft.com",
+  "dependentChangeType": "patch"
+}

From b80c3c988edfe41922f51c2912b7242a37f676a2 Mon Sep 17 00:00:00 2001
From: Sarah Higley <sarah.higley@microsoft.com>
Date: Fri, 28 Jun 2024 12:01:37 -0700
Subject: [PATCH 3/4] put off changing default for legacyTrapFocus

---
 ...cker-compat-bc4d1aaa-945e-4107-9a30-34bbb9550319.json | 7 -------
 ...act-tabster-11eb3b52-85dd-4590-9d26-35b95e3112c6.json | 7 -------
 .../react-tabster/src/hooks/useModalAttributes.ts        | 9 +++++----
 3 files changed, 5 insertions(+), 18 deletions(-)
 delete mode 100644 change/@fluentui-react-datepicker-compat-bc4d1aaa-945e-4107-9a30-34bbb9550319.json
 delete mode 100644 change/@fluentui-react-tabster-11eb3b52-85dd-4590-9d26-35b95e3112c6.json

diff --git a/change/@fluentui-react-datepicker-compat-bc4d1aaa-945e-4107-9a30-34bbb9550319.json b/change/@fluentui-react-datepicker-compat-bc4d1aaa-945e-4107-9a30-34bbb9550319.json
deleted file mode 100644
index 0f1545d15754e..0000000000000
--- a/change/@fluentui-react-datepicker-compat-bc4d1aaa-945e-4107-9a30-34bbb9550319.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "type": "patch",
-  "comment": "feat: update DatePicker to use legacyTrapFocus",
-  "packageName": "@fluentui/react-datepicker-compat",
-  "email": "sarah.higley@microsoft.com",
-  "dependentChangeType": "patch"
-}
diff --git a/change/@fluentui-react-tabster-11eb3b52-85dd-4590-9d26-35b95e3112c6.json b/change/@fluentui-react-tabster-11eb3b52-85dd-4590-9d26-35b95e3112c6.json
deleted file mode 100644
index 82cf6d390f151..0000000000000
--- a/change/@fluentui-react-tabster-11eb3b52-85dd-4590-9d26-35b95e3112c6.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "type": "minor",
-  "comment": "feat: update useModalAttributes to use legacyTrapFocus by default",
-  "packageName": "@fluentui/react-tabster",
-  "email": "sarah.higley@microsoft.com",
-  "dependentChangeType": "patch"
-}
diff --git a/packages/react-components/react-tabster/src/hooks/useModalAttributes.ts b/packages/react-components/react-tabster/src/hooks/useModalAttributes.ts
index 42b52d7ac0a53..08e98412f3381 100644
--- a/packages/react-components/react-tabster/src/hooks/useModalAttributes.ts
+++ b/packages/react-components/react-tabster/src/hooks/useModalAttributes.ts
@@ -12,9 +12,10 @@ export interface UseModalAttributesOptions {
 
   /**
    * Traps focus inside the elements the attributes are applied.
-   * This prop enables traditional force-focus behavior to match previous versions of Fluent
-   * Setting `legacyTrapFocus` to false allows users to tab out of the focus trap and into
-   * the actual browser. This matches the behavior of the native <dialog> element and inert.
+   * This prop enables traditional force-focus behavior to match previous versions of Fluent.
+   * Without this, users can tab out of the focus trap and into the browser chrome.
+   * This matches the behavior of the native <dialog> element and inert.
+   * We recommend setting this to true based on user feedback and consistency.
    */
   legacyTrapFocus?: boolean;
 
@@ -39,7 +40,7 @@ export interface UseModalAttributesOptions {
 export const useModalAttributes = (
   options: UseModalAttributesOptions = {},
 ): { modalAttributes: TabsterTypes.TabsterDOMAttribute; triggerAttributes: TabsterTypes.TabsterDOMAttribute } => {
-  const { trapFocus, alwaysFocusable, legacyTrapFocus = true } = options;
+  const { trapFocus, alwaysFocusable, legacyTrapFocus } = options;
   const tabster = useTabster();
   // Initializes the modalizer and restorer APIs
   if (tabster) {

From cbe3d1596a1c80cb02899a74bcbbebc2f47182d8 Mon Sep 17 00:00:00 2001
From: Sarah Higley <sarah.higley@microsoft.com>
Date: Fri, 28 Jun 2024 12:02:51 -0700
Subject: [PATCH 4/4] update change files

---
 ...picker-compat-3e7cd400-73e6-4dc3-8c12-5878aecc0164.json | 7 +++++++
 ...react-tabster-07357d3b-3b08-41c6-ab4f-d60a839a47e6.json | 7 +++++++
 2 files changed, 14 insertions(+)
 create mode 100644 change/@fluentui-react-datepicker-compat-3e7cd400-73e6-4dc3-8c12-5878aecc0164.json
 create mode 100644 change/@fluentui-react-tabster-07357d3b-3b08-41c6-ab4f-d60a839a47e6.json

diff --git a/change/@fluentui-react-datepicker-compat-3e7cd400-73e6-4dc3-8c12-5878aecc0164.json b/change/@fluentui-react-datepicker-compat-3e7cd400-73e6-4dc3-8c12-5878aecc0164.json
new file mode 100644
index 0000000000000..0f1545d15754e
--- /dev/null
+++ b/change/@fluentui-react-datepicker-compat-3e7cd400-73e6-4dc3-8c12-5878aecc0164.json
@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "feat: update DatePicker to use legacyTrapFocus",
+  "packageName": "@fluentui/react-datepicker-compat",
+  "email": "sarah.higley@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/change/@fluentui-react-tabster-07357d3b-3b08-41c6-ab4f-d60a839a47e6.json b/change/@fluentui-react-tabster-07357d3b-3b08-41c6-ab4f-d60a839a47e6.json
new file mode 100644
index 0000000000000..3b69ed65baedf
--- /dev/null
+++ b/change/@fluentui-react-tabster-07357d3b-3b08-41c6-ab4f-d60a839a47e6.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "docs: update wording for legacyTrapFocus",
+  "packageName": "@fluentui/react-tabster",
+  "email": "sarah.higley@microsoft.com",
+  "dependentChangeType": "none"
+}