fix(react-dialog): aria-* properties should be reassignable (#25092)

change/@fluentui-react-dialog-f651b531-21bb-4a89-823e-d8325ec32762.json

@@ -0,0 +1,7 @@
+{
+ "type": "prerelease",
+ "comment": "fix: aria-* properties should be reassignable",
+ "packageName": "@fluentui/react-dialog",
+ "email": "bernardo.sunderhus@gmail.com",
+ "dependentChangeType": "patch"
+}

packages/react-components/react-dialog/src/components/DialogSurface/useDialogSurface.ts

@@ -82,11 +82,11 @@ export const useDialogSurface_unstable = (
  root: getNativeElementProps(as ?? 'div', {
  'aria-modal': modalType !== 'non-modal',
  role: modalType === 'alert' ? 'alertdialog' : 'dialog',
+ 'aria-describedby': dialogContentId,
+ 'aria-labelledby': props['aria-label'] ? undefined : dialogTitleID,
  ...props,
  ...modalAttributes,
  onKeyDown: handleKeyDown,
- 'aria-describedby': dialogContentId,
- 'aria-labelledby': props['aria-label'] ? undefined : dialogTitleID,
  ref: useMergedRefs(ref, dialogRef),
  }),
  };

packages/react-components/react-dialog/src/components/DialogTrigger/useDialogTrigger.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { useModalAttributes } from '@fluentui/react-tabster';
 import { applyTriggerPropsToChildren, getTriggerChild, useEventCallback } from '@fluentui/react-utilities';
-import { DialogTriggerProps, DialogTriggerState } from './DialogTrigger.types';
+import type { DialogTriggerProps, DialogTriggerState } from './DialogTrigger.types';
 import { useDialogContext_unstable, useDialogSurfaceContext_unstable } from '../../contexts';
 import { useARIAButtonProps } from '@fluentui/react-aria';
 

packages/react-components/react-dialog/src/stories/Dialog/DialogBestPractices.md

@@ -8,12 +8,12 @@
 - Dialog boxes consist of a header (`DialogTitle`), content (`DialogContent`), and footer (`DialogActions`), which should all be included inside a body (`DialogBody`).
 - Validate that people’s entries are acceptable before closing the dialog. Show an inline validation error near the field they must correct.
 - Modal dialogs should be used very sparingly—only when it’s critical that people make a choice or provide information before they can proceed. Thee dialogs are generally used for irreversible or potentially destructive tasks. They’re typically paired with an backdrop without a light dismiss.
-- `DialogSurface` by default has `aria-describedby="dialog-content-id"`, which might not be ideal with complex `DialogContent`, on those scenarios, it is recommended to set `aria-describedby={null}`
+- `DialogSurface` by default has `aria-describedby="dialog-content-id"`, which might not be ideal with complex `DialogContent`, on those scenarios (for example on [with form](#with-form)), it is recommended to set `aria-describedby={undefined}`
 
 ### Don't
 
 - Don't use more than three buttons between `DialogActions`.
-- Don't open a Dialog from a Dialog
-- Don't use a Dialog with no focusable elements
+- Don't open a `Dialog` from a `Dialog`
+- Don't use a `Dialog` with no focusable elements
 
 </details>

packages/react-components/react-dialog/src/stories/Dialog/DialogWithForm.md

@@ -1,3 +1,5 @@
 Having a formulary inside the `Dialog` its quite simple, you simply add a `<form>` element between `DialogSurface` and `DialogBody` to ensure all the content between them are properly wrapped inside the formulary. This allows a button inside `DialogActions` to be properly used as submission button.
 
-Keep in mind that controlling the `open` state of the `Dialog` might be ideal in this scenario, since validation and submission are possibly synchronous activities. For example, closing the `Dialog` only after the submission is successful would require control of the `open` state, to properly set `open` to `false` only once the submission has succeeded.
+> Keep in mind that controlling the `open` state of the `Dialog` might be ideal in this scenario, since validation and submission are possibly synchronous activities. For example, closing the `Dialog` only after the submission is successful would require control of the `open` state, to properly set `open` to `false` only once the submission has succeeded.
+
+> ⚠️ Don't forget to set `aria-describedby={undefined}` for `DialogSurface` to ensure the formulary is not automatically narrated by screen readers.

packages/react-components/react-dialog/src/stories/Dialog/DialogWithForm.stories.tsx

@@ -30,7 +30,7 @@ export const WithForm = () => {
  <DialogTrigger>
  <Button>Open formulary dialog</Button>
  </DialogTrigger>
- <DialogSurface>
+ <DialogSurface aria-describedby={undefined}>
  <form onSubmit={handleSubmit}>
  <DialogBody>
  <DialogTitle>Dialog title</DialogTitle>