Group accessibility-related props of DndContext (#746)

.changeset/accessibility-related-props.md

@@ -0,0 +1,34 @@
+---
+'@dnd-kit/core': major
+---
+
+#### Regrouping accessibility-related props
+
+Accessibility-related props have been regrouped under the `accessibility` prop of `<DndContext>`:
+
+```diff
+<DndContext
+- announcements={customAnnouncements}
+- screenReaderInstructions={customScreenReaderInstructions}
++ accessibility={{
++  announcements: customAnnouncements,
++  screenReaderInstructions: customScreenReaderInstructions,
++ }}
+```
+
+This is a breaking change that will allow easier addition of new accessibility-related features without overloading the props namespace of `<DndContext>`.
+
+#### Accessibility-related DOM nodes are no longer portaled by default
+
+The DOM nodes for the screen reader instructions and announcements are no longer portaled into the `document.body` element by default.
+
+This change is motivated by the fact that screen readers do not always announce ARIA live regions that are rendered on the `document.body`. Common examples of this include when rendering a `<DndContext>` within a `<dialog>` element or an element that has `role="dialog"`, only ARIA live regions rendered within the dialog will be announced.
+
+Consumers can now opt to render announcements in the portal container of their choice using the `container` property of the `accessibility` prop:
+
+```diff
+<DndContext
++ accessibility={{
++  container: document.body,
++ }}
+```

packages/core/src/components/Accessibility/Accessibility.tsx

@@ -5,23 +5,27 @@ import {HiddenText, LiveRegion, useAnnouncement} from '@dnd-kit/accessibility';
 
 import type {Announcements, ScreenReaderInstructions} from './types';
 import type {UniqueIdentifier} from '../../types';
-import {defaultAnnouncements} from './defaults';
+import {
+  defaultAnnouncements,
+  defaultScreenReaderInstructions,
+} from './defaults';
 import {DndMonitorArguments, useDndMonitor} from '../../hooks/monitor';
 
 interface Props {
   announcements?: Announcements;
-  screenReaderInstructions: ScreenReaderInstructions;
+  container?: Element;
+  screenReaderInstructions?: ScreenReaderInstructions;
   hiddenTextDescribedById: UniqueIdentifier;
 }
 
 export function Accessibility({
   announcements = defaultAnnouncements,
+  container,
   hiddenTextDescribedById,
-  screenReaderInstructions,
+  screenReaderInstructions = defaultScreenReaderInstructions,
 }: Props) {
   const {announce, announcement} = useAnnouncement();
   const liveRegionId = useUniqueId(`DndLiveRegion`);
-
   const [mounted, setMounted] = useState(false);
 
   useEffect(() => {
@@ -53,16 +57,19 @@ export function Accessibility({
     )
   );
 
-  return mounted
-    ? createPortal(
-        <>
-          <HiddenText
-            id={hiddenTextDescribedById}
-            value={screenReaderInstructions.draggable}
-          />
-          <LiveRegion id={liveRegionId} announcement={announcement} />
-        </>,
-        document.body
-      )
-    : null;
+  if (!mounted) {
+    return null;
+  }
+
+  const markup = (
+    <>
+      <HiddenText
+        id={hiddenTextDescribedById}
+        value={screenReaderInstructions.draggable}
+      />
+      <LiveRegion id={liveRegionId} announcement={announcement} />
+    </>
+  );
+
+  return container ? createPortal(markup, container) : markup;
 }

packages/core/src/components/Accessibility/defaults.ts

@@ -1,6 +1,6 @@
 import type {Announcements, ScreenReaderInstructions} from './types';
 
-export const screenReaderInstructions: ScreenReaderInstructions = {
+export const defaultScreenReaderInstructions: ScreenReaderInstructions = {
   draggable: `
     To pick up a draggable item, press the space bar.
     While dragging, use the arrow keys to move the item.

packages/core/src/components/Accessibility/index.ts

@@ -1,3 +1,6 @@
 export {Accessibility} from './Accessibility';
-export {defaultAnnouncements, screenReaderInstructions} from './defaults';
+export {
+  defaultAnnouncements,
+  defaultScreenReaderInstructions,
+} from './defaults';
 export type {Announcements, ScreenReaderInstructions} from './types';

packages/core/src/components/DndContext/DndContext.tsx

@@ -74,7 +74,6 @@ import type {
 import {
   Accessibility,
   Announcements,
-  screenReaderInstructions as defaultScreenReaderInstructions,
   ScreenReaderInstructions,
 } from '../Accessibility';
 
@@ -87,14 +86,17 @@ import type {MeasuringConfiguration} from './types';
 
 export interface Props {
   id?: string;
+  accessibility?: {
+    announcements?: Announcements;
+    container?: Element;
+    screenReaderInstructions?: ScreenReaderInstructions;
+  };
   autoScroll?: boolean | AutoScrollOptions;
-  announcements?: Announcements;
   cancelDrop?: CancelDrop;
   children?: React.ReactNode;
   collisionDetection?: CollisionDetection;
   measuring?: MeasuringConfiguration;
   modifiers?: Modifiers;
-  screenReaderInstructions?: ScreenReaderInstructions;
   sensors?: SensorDescriptor<any>[];
   onDragStart?(event: DragStartEvent): void;
   onDragMove?(event: DragMoveEvent): void;
@@ -129,14 +131,13 @@ enum Status {
 
 export const DndContext = memo(function DndContext({
   id,
+  accessibility,
   autoScroll = true,
-  announcements,
   children,
   sensors = defaultSensors,
   collisionDetection = rectIntersection,
   measuring,
   modifiers,
-  screenReaderInstructions = defaultScreenReaderInstructions,
   ...props
 }: Props) {
   const store = useReducer(reducer, undefined, getInitialState);
@@ -682,9 +683,8 @@ export const DndContext = memo(function DndContext({
         </PublicContext.Provider>
       </InternalContext.Provider>
       <Accessibility
-        announcements={announcements}
+        {...accessibility}
         hiddenTextDescribedById={draggableDescribedById}
-        screenReaderInstructions={screenReaderInstructions}
       />
     </DndMonitorContext.Provider>
   );

packages/core/src/components/index.ts

@@ -1,4 +1,7 @@
-export {defaultAnnouncements} from './Accessibility';
+export {
+  defaultAnnouncements,
+  defaultScreenReaderInstructions,
+} from './Accessibility';
 export type {Announcements, ScreenReaderInstructions} from './Accessibility';
 export {DndContext} from './DndContext';
 export type {

packages/core/src/index.ts

@@ -1,15 +1,16 @@
 export {
   DndContext,
   DragOverlay,
-  DragOverlayProps,
   defaultAnnouncements,
+  defaultScreenReaderInstructions,
   defaultDropAnimation,
   defaultDropAnimationSideEffects,
 } from './components';
 export type {
   Announcements,
   CancelDrop,
   DndContextProps,
+  DragOverlayProps,
   DropAnimation,
   DropAnimationFunction,
   DropAnimationFunctionArguments,

stories/2 - Presets/Sortable/Sortable.tsx

@@ -188,8 +188,10 @@ export function Sortable({
 
   return (
     <DndContext
-      announcements={announcements}
-      screenReaderInstructions={screenReaderInstructions}
+      accessibility={{
+        announcements,
+        screenReaderInstructions,
+      }}
       sensors={sensors}
       collisionDetection={collisionDetection}
       onDragStart={({active}) => {

stories/3 - Examples/Tree/SortableTree.tsx

@@ -189,7 +189,7 @@ export function SortableTree({
 
   return (
     <DndContext
-      announcements={announcements}
+      accessibility={{announcements}}
       sensors={sensors}
       collisionDetection={closestCenter}
       measuring={measuring}