feat(react-dialog): add appearance to backdrop slot

[mainframev]

This pull request introduces a new appearance property to the DialogSurface backdrop slot in @fluentui/react-dialog, enabling explicit control over the dialog's backdrop appearance. By default, the dialog automatically chooses between a dimmed or transparent backdrop based on its nesting context, but this change allows developers to override that behavior. The update includes type definitions, logic for resolving the backdrop appearance, style adjustments, documentation, and a new story demonstrating the feature.

• Added DialogBackdropSlotProps type to support an appearance prop ('dimmed' or 'transparent') for the backdrop slot in DialogSurface.

Previous Behavior

The dimmed background applied based on the Dialog context. Inside OverlayDrawer dialogs become nested and inner Dialog does not have dimmed background. The only way to apply the dimmed background for inner Dialog is via backdrop slot in DialogSurface

New Behavior

Can be controlled via backdropAppearance without the need to use hack with passing custom styled backdrop to DialogSurface

Related Issue(s)

Related older discussion

• Fixes [Bug]: Dialog nested inside Drawer renders transparent backdrop (background not dimmed) #35653

[github-actions]

📊 Bundle size report

Package & Exports	Baseline (minified/GZIP)	PR	Change
react-components react-components: entire library	1.291 MB 322.99 kB	1.292 MB 323.043 kB	167 B 53 B

Unchanged fixtures

Package & Exports	Size (minified/GZIP)
react-components react-components: Button, FluentProvider & webLightTheme	70.224 kB 19.89 kB
react-components react-components: Accordion, Button, FluentProvider, Image, Menu, Popover	237.179 kB 68.482 kB
react-components react-components: FluentProvider & webLightTheme	43.523 kB 13.978 kB
react-dialog Dialog (including children components)	102.078 kB 30.379 kB
react-portal-compat PortalCompatProvider	8.386 kB 2.624 kB
react-timepicker-compat TimePicker	108.15 kB 35.693 kB

_{🤖 This report was generated against 93f8af06be5ab06d974cf936a462d739a98231fb}

[github-actions]

Pull request demo site: URL

[dmytrokirpa]

TBH, I'm not sure I understand the purpose of the hasParentDialog={false} API, as its meaning isn't clear and it doesn't actually change the component's parent.

@mainframev, have you considered adding a prop to prevent the backdrop from being transparent, even when the dialog is nested? This might be clearer than using hasParentDialog={false}, especially since there is a parent dialog present.

[mainframev]

TBH, I'm not sure I understand the purpose of the hasParentDialog={false} API, as its meaning isn't clear and it doesn't actually change the component's parent.

@mainframev, have you considered adding a prop to prevent the backdrop from being transparent, even when the dialog is nested? This might be clearer than using hasParentDialog={false}, especially since there is a parent dialog present.

Yeah, I agree that it was not very well thought through very well. I thought in the direction of adding a backdropAppearance prop instead, I updated the suggestion, this should be more clear now with SB example and updated prop. Thank you :)

This would be a convenient prop that makes users lives easier, especially since we have already received several questions about this. Alternatively, we could approach this differently by exposing a data attribute on the backdrop slot, for example: backdrop={{ 'data-backdrop-appearance': 'dimmed' }}. This could help avoid potential confusion caused by having both backdrop and backdropAppearance props at the same time.

[dmytrokirpa]

LGMT, just two things to address and should be good to go:

• Clarify why do we need to remove the appearance prop from the backdrop slot
• Could we add some tests (VR, e2e, etc) to test the old/new behavior?