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.