[API Spec] SplitMenuFlyoutItem control

[dipeshmsft]

This is an API Spec PR for the proposed SplitMenuFlyoutItem control.

PR Type

Please check the type of change your PR introduces:

• Bugfix
• Feature
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no api changes)
• Build related changes
• Documentation content changes
• Other (please describe):

Description

The SplitMenuFlyoutItem control is proposed to be a new addition to the WinUI library, designed to provide a split button experience within a menu flyout. This control derives from MenuFlyoutItem and introduces a dual-button interface consisting of a primary button and a flyout button.

Motivation and Context

This functionality will allow developers to expose a default primary action while also offering additional options through an attached dropdown — ideal for condensing complex functionality into a smaller footprint and saving overall menu length.

How Has This Been Tested?

• I have performed a self-review of my own code
• I have added tests to cover my changes

Screenshots (if appropriate):

Attached in the document.

[eduardobragaxz]

AppBarSplitButton would be nice too 👀

[michael-hawker]

I've added this to the public api review process board: https://aka.ms/winappsdk/api-specs-review

This PR will be open for feedback for a month from its opening: October 30th – November 30th

FYI @dipeshmsft

[whiskhub]

Please consider referencing all resources in XAML with ThemeResource, even values like thickness, height etc. This allows users to overwrite resources for lightweight styling. See #6945

For example, MenuFlyoutItemThemePaddingNarrow, SplitMenuFlyoutItemSeparatorHeight, SplitMenuFlyoutItemChevronButtonWidth, MenuFlyoutItemChevronMargin seem to be referenced as StaticResource right now. 3e4702c...b05521d#diff-2ded3dd0ba19e54f4d02039304a6094d2945899e86e8e039e91af5d738da83c9R602

[riverar]

I have UX concerns about the current proposal/implementation where the context menu item reads "Compress to ZIP" but opens a sub-menu with alternative formats (7z, tar.gz, etc.).

The chevron (>) establishes a visual contract that the sub-menu contains sub-options or refinements of the parent item. However, this control actually presents alternative actions that contradict the parent label. When users see "Compress to ZIP >", they reasonably expect ZIP-related options (compression levels, encryption, split archives), not completely different formats.

Example: Imagine a context menu item labeled "Email to John >" that opens a sub-menu with "Slack John", "Call John", "Text John". While all communicate with John, the parent item explicitly promised email.

Are there existing Windows patterns or any other examples to support this "specific action > alternative actions" model that I'm not aware of?

[riverar]

That's confusing. I think if a user is keyboarding through a context menu with items that can open sub-menus, they would expect up/down to select only primary items. If they are interested in other options, they will explore those by moving to the item and pressing right-arrow.

(LTR layout assumed)

[dipeshmsft]

We chose the above behavior to accommodate users who would be using a screen reader. If we use Up/Down arrow keys to navigate to primary button and then to next item, it hampers the discoverability of the secondary button.

This same pattern is followed in Teams desktop application.
Here is a sample of the Split Menu Item that already exists in Fluent UI React 9: https://storybooks.fluentui.dev/react/?path=/docs/components-menu-menu--docs#split-menu-item

[riverar]

Also confusing. I'd expect right-arrow to open the sub-menu.

[dipeshmsft]

Referring to the comment above. Following the Fluent UI behavior for this control.

Although in case of previous variations of this control, like Microsoft PowerPoint, we have the behavior that you have mentioned.

[riverar]

If this control is already in experimental3, which is already in the pipeline for release, what impact will this PR really have?

[dipeshmsft]

@riverar

I have UX concerns about the current proposal/implementation where the context menu item reads "Compress to ZIP" but opens a sub-menu with alternative formats (7z, tar.gz, etc.).
The chevron (>) establishes a visual contract that the sub-menu contains sub-options or refinements of the parent item. However, this control actually presents alternative actions that contradict the parent label. When users see "Compress to ZIP >", they reasonably expect ZIP-related options (compression levels, encryption, split archives), not completely different formats.

"Compress to ZIP" scenario may not be the best scenario for SplitMenuFlyoutItem and maybe more suited for MenuFlyoutSubItem.

I would like to draw your attention to the Paste example, where there are different ways of performing the paste - "Paste as Text", "Paste with Merge Formatting", "Paste with Source Formatting", etc. This is one of the true examples of what we are trying to achieve using this control. If there are multiple ways of performing one operation and the app developer wants to set one as the default mode operation, those scenarios are the ones that we are trying to support using this control.

In the example of having a menu item "Email to John" and then inside that command having sub-menu items like "Slack to John", "Call John", this is geared towards the default mode of action for a user. Say it is by mail, so we show that in the primary part, and other parts of making contact are secondary, so they are put in the sub menu item.

However, I think the control is general enough to support both the cases : having alternate actions grouped together, and handling different variations of the same action.

In the light of the confusion this is creating I will go ahead and modify the usage examples in the API spec.

[dipeshmsft]

If this control is already in experimental3, which is already in the pipeline for release, what impact will this PR really have?

@riverar, we have done 2 passes on internal review for this control, however since this is still in experimental, we are open to suggestions.

[pranav-gupta-msft]

nit: Images can be mid-aligned.

[Jay-o-Way]

I just wanna say that this document does not follow MS Learn style/formatting guidelines.

• https://learn.microsoft.com/contribute/content/text-formatting-guidelines
• https://learn.microsoft.com/contribute/content/markdown-reference

Some examples: (not limited to)

• UI elements, like menu items, dialog names, and names of text boxes, should be in bold text.
• Keys and keyboard shortcuts: use "select" and <kbd> tags
• Empty lines between headers, lists, code blocks etc.
• Each Markdown file must have one and only one H1 heading.
• Spelling, please
• Don't use bold as an alternative for a header

[dipeshmsft]

@Jay-o-Way

I just wanna say that this document does not follow MS Learn style/formatting guidelines.

This document follows the API Spec template provided in the repo: https://github.com/microsoft/WindowsAppSDK/blob/main/specs/spec_template.md

I will take a look at rest of the formatting issues and update the spec accordingly.

[Jay-o-Way]

This document follows the API Spec template provided in the repo:

😂 Hasn't been touched in at least 5 years though...

[d2phap]

@dipeshmsft Does it support KeyboardAccelerators? I don't see it mentioned here and no screenshot, too