Add WrapPanel API Spec based on Windows Community Toolkit (WCT)

[michael-hawker]

This PR adds the dev and functional spec for WinUI WrapPanel (from Windows Community Toolkit).

Community members can provide feedback by commenting directly on the PR, or through a code suggestion with GitHub tools.
Feedback should be constructive and specific, addressing potential use cases, design concerns, and functionality.

This PR will be open for feedback for a month: October 27th – November 27th
For more info on the public api review process: https://aka.ms/winappsdk/api-specs-review

[Poker-sang]

How about changing HorizontalSpacing and VerticalSpacing to ItemSpacing and LineSpacing? This is consistent with the naming precedent in LinedFlowLayout and better suits users' intuition.

[mdtauk]

How about changing HorizontalSpacing and VerticalSpacing to ItemSpacing and LineSpacing? This is consistent with the naming precedent in LinedFlowLayout and better suits users' intuition.

Not sure I agree, as because "Lined" is in the name, the Line spacing makes more sense, and has context which does not exist with a wrap panel.

[mdtauk]

Is there scope to allow different behaviours for how items are placed?

With the Files app, we have come across an issue where each row uses the calculated height from only the first item in the panel, where we would like each row to take it's height from the tallest item that wraps into it?

I know this would likely be considered a breaking change, but if it were a new property that could be toggled/switched, it would make the control more flexible. File Explorer's grid view uses this behaviour.

File Explorer

[zxbmmmmmmmmm]

How about changing HorizontalSpacing and VerticalSpacing to ItemSpacing and LineSpacing? This is consistent with the naming precedent in LinedFlowLayout and better suits users' intuition.

Not sure I agree, as because "Lined" is in the name, the Line spacing makes more sense, and has context which does not exist with a wrap panel.

This is discussed previously in AvaloniaUI/Avalonia#18079. I think ItemSpacing/LineSpacing can avoid user confusion caused by different Orientation of wrap panel.

[mdtauk]

How about changing HorizontalSpacing and VerticalSpacing to ItemSpacing and LineSpacing? This is consistent with the naming precedent in LinedFlowLayout and better suits users' intuition.

Not sure I agree, as because "Lined" is in the name, the Line spacing makes more sense, and has context which does not exist with a wrap panel.

This is discussed previously in AvaloniaUI/Avalonia#18079. I think ItemSpacing/LineSpacing can avoid user confusion caused by different Orientation of wrap panel.

You could do maybe Row spacing, and Item spacing, which may make sense, but HorizontalSpacing and VerticalSpacing is consistent with many other controls, and should still be relevant regardless of orientation.

You could also have ItemHorizontalSpacing and ItemVerticalSpacing, which should also be agnostic regardless of the panel's Orientation.

[Poker-sang]

You could do maybe Row spacing, and Item spacing, which may make sense, but HorizontalSpacing and VerticalSpacing is consistent with many other controls, and should still be relevant regardless of orientation.

You could also have ItemHorizontalSpacing and ItemVerticalSpacing, which should also be agnostic regardless of the panel's Orientation.

@mdtauk RowSpacing, and ItemSpacing, make more sense than H/V Spacing, but not as good as LineSpacing.

If you set Orientation to Horizontal, the Line is a Column.

And ItemHorizontalSpacing and ItemVerticalSpacing is a even worse naming than H/V spacing.

First, it's tied to direction, causing confusion when switching Orientation. Second, the word Item does not make any sense; the spacing of a Line is not the spacing of an Item, which adds to the confusion. I'm sorry, but I completely disagree with you.

[Poker-sang]

This is LinedFlowLayout. Doesn't it look exactly like WrapPanel?

[michael-hawker]

Is there scope to allow different behaviours for how items are placed?

With the Files app, we have come across an issue where each row uses the calculated height from only the first item in the panel, where we would like each row to take it's height from the tallest item that wraps into it?

I know this would likely be considered a breaking change, but if it were a new property that could be toggled/switched, it would make the control more flexible. File Explorer's grid view uses this behaviour.

@mdtauk the current behavior of the WrapPanel (which is the same as it is in the Windows Community Toolkit) is that each row's height is calculated from the largest item in that row. You can see that with the random image sizes in the sample gallery:

So, I think that would cover your scenario? Unless I'm misunderstanding. But it should be called out within the spec somewhere on these expectations.

[michael-hawker]

@zxbmmmmmmmmm thanks to the link to the Avalonia discussion, that's useful context. I'll take a look.

[mdtauk]

Is there scope to allow different behaviours for how items are placed?
With the Files app, we have come across an issue where each row uses the calculated height from only the first item in the panel, where we would like each row to take it's height from the tallest item that wraps into it?
I know this would likely be considered a breaking change, but if it were a new property that could be toggled/switched, it would make the control more flexible. File Explorer's grid view uses this behaviour.

@mdtauk the current behavior of the WrapPanel (which is the same as it is in the Windows Community Toolkit) is that each row's height is calculated from the largest item in that row. You can see that with the random image sizes in the sample gallery:

So, I think that would cover your scenario? Unless I'm misunderstanding. But it should be called out within the spec somewhere on these expectations.

Can the items stretch to match the height of the tallest item, to fill the "row height"?

[roxk]

Is there scope to allow different behaviours for how items are placed?
With the Files app, we have come across an issue where each row uses the calculated height from only the first item in the panel, where we would like each row to take it's height from the tallest item that wraps into it?
I know this would likely be considered a breaking change, but if it were a new property that could be toggled/switched, it would make the control more flexible. File Explorer's grid view uses this behaviour.

@mdtauk the current behavior of the WrapPanel (which is the same as it is in the Windows Community Toolkit) is that each row's height is calculated from the largest item in that row. You can see that with the random image sizes in the sample gallery:

So, I think that would cover your scenario? Unless I'm misunderstanding. But it should be called out within the spec somewhere on these expectations.

Can the items stretch to match the height of the tallest item, to fill the "row height"?

IMO a more complete version of this ask is: WrapPanel should respect HorizontalAlignment and VerticalAlignment where applicable. Filling row height in this case would mean setting a horizontal wrap panel's child's VerticalAlignment="Stretch"

[michael-hawker]

Thanks @neerajmsgithub for the review, I was a bit confused at first until I just referenced existing similar classes in the main idl file (src\dxaml\xcp\dxaml\idl\winrt\controls\microsoft.ui.xaml.controls.controls.idl); it was a good reference.

Also, for future reference, you can make suggestions directly as edits that I could accept in the file with this toolbar button:

That'll also allow me to easily credit your account for the suggestions within the commit.

[michael-hawker]

@kmahone @neerajmsgithub I've updated the spec based on all review comments, think this should be good to close on. Thanks!

[michael-hawker]

This is LinedFlowLayout. Doesn't it look exactly like WrapPanel?

@Poker-sang sorry, I didn't reply to your comment. LinedFlowLayout has a few differences. First it's an ItemsRepeater Layout vs. a general Panel, so it's meant for larger virtualized collections. As part of that it assumes all items will share the same height, where WrapPanel doesn't have that restriction.

It does use Item/LineSpacing naming though, so we'll update to align to it and Avalonia.

[michael-hawker]

Thanks everyone for the great commentary and insights. It's really made a great collaboration here and improving the API surface not just now but for the future as well.

I'll merge this and update the code to match, not sure if it'll make experimental4 though. I was hoping to get to that started last week, but I was impacted logistically by the flooding (all is good though).

[michael-hawker]

Oh cool, I can see the PRs got mirrored and me putting the link in the title worked to reference it here! 😊

These updates should both be coming in experimental4 when it drops. 🎉