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 323 kB	1.291 MB 323.078 kB	327 B 78 B

Unchanged fixtures

Package & Exports	Size (minified/GZIP)
react-components react-components: Button, FluentProvider & webLightTheme	70.397 kB 19.96 kB
react-components react-components: Accordion, Button, FluentProvider, Image, Menu, Popover	237.306 kB 68.52 kB
react-components react-components: FluentProvider & webLightTheme	43.612 kB 14.022 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 f17bb7ecaae51c2c01401a7d37e09a7fde13a373}

[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?

[layershifter]

I don't have comments to the PR itself, it's LGTM. However, I am unsure that it's the right fix for #35653. I got the point about explicit control, but it's not was reported in the original issue.

The root cause is:

const isNestedDialog = useHasParentContext(DialogContext);

And as OverlayDrawer renders Dialog, we get this "false positive". I propose to create a separate boolean-based (or enum-based) context that controls behavior of backdrop, so OverlayDrawer can override its value with false or transparent.

We can also consider adding a new property to an existing DialogContext, but IMO it will be more complex to override it in OverlayDrawer.

@mainframev @dmytrokirpa WDYT?

[mainframev]

I don't have comments to the PR itself, it's LGTM. However, I am unsure that it's the right fix for #35653. I got the point about explicit control, but it's not was reported in the original issue.

The root cause is:

const isNestedDialog = useHasParentContext(DialogContext);

And as OverlayDrawer renders Dialog, we get this "false positive". I propose to create a separate boolean-based (or enum-based) context that controls behavior of backdrop, so OverlayDrawer can override its value with false or transparent.

We can also consider adding a new property to an existing DialogContext, but IMO it will be more complex to override it in OverlayDrawer.

@mainframev @dmytrokirpa WDYT?

Good point. We can add that and keep both, Dialog context for controlling backdrop in OverlayDrawer will be a default fixing the issue, explicit override via slot is still a good way for one-off override without using a provider, if user wants to opt-out from nested dialogs context check

[layershifter]

Let's avoid any logic in context hooks