fix(wrapFocus): add experimental option to wrap focus without sentine…

…ls (#15868)

* fix(ComposedModal): add option to wrap focus without sentinels

* feat(wrapFocus): add wrapFocusWithoutSentinels

* chore(wrapFocus): place new behavior behind a feature flag

* docs(focuswrap): add feature flag stories for new wrap focus

* docs(focuswrap): remove feature flag info from default mdx

packages/feature-flags/feature-flags.yml

@@ -42,3 +42,7 @@ feature-flags:
     description: >
       Enable the new TreeView controllable API
     enabled: false
+  - name: enable-experimental-focus-wrap-without-sentinels
+    description: >
+      Enable the new focus wrap behavior that doesn't use sentinel nodes
+    enabled: false

packages/react/package.json

@@ -65,6 +65,7 @@
     "lodash.throttle": "^4.1.1",
     "prop-types": "^15.7.2",
     "react-is": "^18.2.0",
+    "tabbable": "^6.2.0",
     "use-resize-observer": "^6.0.0",
     "wicg-inert": "^3.1.1",
     "window-or-global": "^1.0.1"

packages/react/src/components/ComposedModal/ComposedModal.featureflag.mdx

@@ -0,0 +1,27 @@
+# ComposedModal
+
+[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/ComposedModal)
+ | 
+[Usage guidelines](https://www.carbondesignsystem.com/components/modal/usage)
+ | 
+[Accessibility](https://www.carbondesignsystem.com/components/modal/accessibility)
+
+## Experimental focus wrap without sentinels
+
+`ComposedModal` supports the `enable-experimental-focus-wrap-without-sentinels`
+feature flag. This enables a new approach to the focus wrap behavior that
+modifies the DOM to no longer include hidden "sentinel nodes" used to mark the
+beginning and end of the wrapped focus. The new behavior looks at all
+interactive child nodes and wraps focus based on tabbable order of those nodes.
+The focus direction is determined whether `tab` is being pressed (forward) or
+`shift`+`tab` is being pressed (backwards). In javascript you can enable this
+feature flag to use the new focus wrap behavior.
+
+```js
+<FeatureFlags
+  flags={{
+    'enable-experimental-focus-wrap-without-sentinels': true,
+  }}>
+  <ComposedModal />
+</FeatureFlags>
+```