Upcoming feature flag filter

[dempseyatgithub]

This PR implements a dedicated filter button for proposals with an upcoming feature flag as described in Issue #261.

From my testing everything is working as intended. The feature flag filter correctly interacts with the status/version filter. The per-status count values update correctly. The URL fragment that includes the search/filter settings now includes the feature flag filter state and is read and written as expected.

I have tested with multiple iOS devices and the tap targets of the filter buttons seem to be large enough to tap each easily.

• Add click handler to flag filter button
• Add method that filters out proposals without a UFF
• Add a URL that links to info about upcoming feature flags
• Add suffix to status string 'with upcoming feature flags'
  • Include link to info about UFFs
  • Use correct pluralization for status string
• Add flag filter button element and SVG to _dashboard.html
• Add element id to status filter and flag filter buttons
• Add new CSS class for flag icon active state
• Resolves Searching for "Feature Identifier" on swift.org/swift-evolution #261

With Upcoming Feature Flag Filter Off:

With Upcoming Feature Flag Filter On:

The text 'upcoming feature flag' links to info about upcoming feature flags, in this PR, the proposal that introduces them.

[dempseyatgithub]

Even though this is still a draft PR, I'd appreciate if folks could take a look and give any high-level feedback or feedback on specifics in the original post.

[dempseyatgithub]

@swift-ci test

[dempseyatgithub]

I addressed the one known issue and removed it from the initial comment:

1. On mobile devices the order of the elements rearrange and the flag filter button ends up next to the status text/link of the status filter button. This should be addressed before committing.

I still need to test tap targets for mobile and adjust if necessary. I think then the PR should be ready to come out of draft.

[dempseyatgithub]

@swift-ci test

[dempseyatgithub]

I tested the filter buttons on an iPhone SE (3rd gen) and iPhone 14 Pro.

The tap target sizes and spacing between the buttons seemed to be enough to tap each easily.

That was the last item I wanted to check before moving this from draft, so moving this to be ready to review.

[dempseyatgithub]

@swift-ci test

[dempseyatgithub]

@swift-ci test

[dempseyatgithub]

@swift-ci test

[kaishin]

Really nice quality of life improvement. I found no issues with the code or the interaction/behavior.

I'm curious about the benefit of giving the upcoming feature flag filter its own toggle button as opposed to adding it as a filter option to the pre-existing filter list. Beside introducing the usability challenges that you had to work around in the PR, it will likely invite us to introduce more filter buttons in the future, which in turn will resurface these challenges and likely additional ones compared to a unified, label-only list.

Here is a mock-up of how it might look like, wording aside:

Since this is a user-facing feature that I assume we want to draw some attention to, I'd personally suggest we agree on the UX direction before merging the PR as opposed to merging it then changing course, but feel free to disagree!

[kaishin]

Regarding the mock-up above, we can also apply a bit more progressive disclosure by only showing the UFF toggle once the Implemented filter is selected, similar to Swift version filters. This would eliminate all invalid status-UFF combinations. The tradeoff of course being less discoverability.

[dempseyatgithub]

@kaishin Thank you very much for the feedback!

In the Issue that this PR addresses, I suggested three different ways of exposing this feature, including my own thoughts of the pros and cons for each approach:

Three Options For Adding Upcoming Feature Flag Filter

I did a few different mockups that included Upcoming Feature Flags in the existing status filtering UI.

At least for me, to keep with the style of the existing status filtering UI, any option seems to be an extremely heavyweight UI addition for what is essentially an on-off button.

I don't think people will ever be searching for proposals without an upcoming feature flag, so in my mockups I used a single on-off toggle or checkbox.

Beside introducing the usability challenges that you had to work around in the PR

I'm not sure which usability challenges you mean, I think there were two:

• Making sure the tap targets were suitable on mobile devices, which didn't require any changes
• Shortening the names of the statuses for the status filter status string in very small screen widths.

I think the second usability challenge becomes even more of a challenge if the flag filter is combined with the status filter and a single status string needs to report the settings of both the status filter and the flag filter.

it will likely invite us to introduce more filter buttons in the future, which in turn will resurface these challenges and likely additional ones compared to a unified, label-only list.

The Swift Evolution dashboard has been around for a seven or eight years now. I have been a heavy user of it and this is the first time I've thought that it needed an additional filter. It is also the first time one has been requested in a year of the site being open source.

I suspect that there won't be much call for adding additional filter buttons, unless another important piece of information is included in the Swift Evolution proposals themselves. The Swift Evolution process has been very stable over a period of years and does not have a major change often, which makes that unlikely.

If we do need to add additional filter buttons beyond this one, then we likely would want to redo a number of things about the existing user interface, including the filter status string.

I have already seen two blog posts telling people to grep through source files in the Swift compiler project to find a list of upcoming feature flags.

So, it was also my hope that we could provide the community a way to find upcoming feature flags sooner rather than later. I believe this approach introduces the least number of implementation changes, the smallest number of filter status string challenges, avoids the need to do serious rework and rewriting of existing pieces of the page and also gives upcoming feature flags the most discoverability.

Regarding the mock-up above, we can also apply a bit more progressive disclosure by only showing the UFF toggle once the Implemented filter is selected, similar to Swift version filters. This would eliminate all invalid status-UFF combinations. The tradeoff of course being less discoverability.

I think that because the version filters are also only visible when Implemented is selected, it makes for a very complicated, heavy user interface. (Come to think of it, this is true whether there is progressive disclosure or not.)

Also note that proposals that are going through review or that have been accepted can have an Upcoming Feature Flag if one is included in the evolution proposal. Seeing a proposal in review with one of these flags is a signal the proposal includes source-breaking changes.

Here is a mock-up of how it might look like, wording aside:

When I was doing the mockups I linked to above, I also found that since these are called "upcoming feature flags" that having actual named buttons also does make for a naming challenge. Matching the style of the existing status / version toggle buttons makes the 'Has Upcoming Feature Flag' button an enormous button.

To stay with the existing filter panel style, it also seems incredibly heavyweight to need a section title for a single toggle.

Since this is a user-facing feature that I assume we want to draw some attention to, I'd personally suggest we agree on the UX direction before merging the PR as opposed to merging it then changing course, but feel free to disagree!

I agree, I began investigating what it would take to add the filter and it was a short hop to implement it instead of just experimenting.

I encourage folks to read the different options I proposed in the reported issue: Three Options For Adding Upcoming Feature Flag Filter.

That post has mockups for each option and my list of pros and cons for each option.

One additional point that makes me lean in favor of the dedicated filter button is the implementation in this PR provides an opportunity to educate the community about upcoming feature flags. I think most people have an intuitive sense of what statuses like "Accepted", "Implemented", and "Rejected" are, or what filter buttons labeled "Swift 5.7", "Swift 5.8" will do.

On the other hand "Upcoming Feature Flags" are something new and unique to Swift that need explanation. When the filter is turned on, the phrase 'upcoming feature flags' currently links to the evolution proposal about it. I have posted a draft blog post 'Using Upcoming Feature Flags' to the website workgroup forum which covers what upcoming feature flags are, the problem they solve, their benefits and how to to use them. I think that will be a useful blog post on its own, but also a good destination to link to as a more practical guide than the evolution proposal, which is a design document, not a user-facing guide.

One other data point: the community member who filed the issue also preferred the separate flag filter button option. We could potentially post the options to the Swift Website forum to get additional community feedback.

But again, one of the things that struck me is the number of people already recommending grepping through Swift source code to find identifiers that we have already added to the dashboard, so time also seemed to be of the essence.

[kaishin]

@dempseyatgithub I somehow missed the original discussion around the various options, apologies for that. Thank you for spending the time exploring the alternatives, it makes discussing and taking these decisions much easier.

At least for me, to keep with the style of the existing status filtering UI, any option seems to be an extremely heavyweight UI addition for what is essentially an on-off button.

I don't think people will ever be searching for proposals without an upcoming feature flag, so in my mockups I used a single on-off toggle or checkbox.

That's a very good point and a route I considered as well. My feedback mostly concerns extracting the new toggle out of the filter list, not how it presents itself.

I'm not sure which usability challenges you mean, I think there were two:

Tap target size and spacing on touch devices is the one I was mainly referring to.

I think the second usability challenge becomes even more of a challenge if the flag filter is combined with the status filter and a single status string needs to report the settings of both the status filter and the flag filter.

I thought about the status string indeed. One common solution is to display the number of filters applied instead of what the actual filters are.

I suspect that there won't be much call for adding additional filter buttons, unless another important piece of information is included in the Swift Evolution proposals themselves. The Swift Evolution process has been very stable over a period of years and does not have a major change often, which makes that unlikely.
If we do need to add additional filter buttons beyond this one, then we likely would want to redo a number of things about the existing user interface, including the filter status string.

These are all fair points.

I think that because the version filters are also only visible when Implemented is selected, it makes for a very complicated, heavy user interface. (Come to think of it, this is true whether there is progressive disclosure or not.)

No doubt it complicates the UI and the front-end implementation, but it makes sense if we consider Swift versions a property that is exclusive to implemented features. One thing we can explore is disabling Swift versions instead of hiding them altogether.

Also note that proposals that are going through review or that have been accepted can have an Upcoming Feature Flag if one is included in the evolution proposal. Seeing a proposal in review with one of these flags is a signal the proposal includes source-breaking changes.

Word. This sounds quite useful indeed.

To stay with the existing filter panel style, it also seems incredibly heavyweight to need a section title for a single toggle.

I am not sure I share this opinion, but I can see it feeling overkill.

One additional point that makes me lean in favor of the dedicated filter button is the implementation in this PR provides an opportunity to educate the community about upcoming feature flags.

The discussion in the original issue and the reply above perfectly answer the question regarding the benefit of using a standalone button. That being said doing that while leaving the previous one intact is the main source of my reluctance around this particular implementation. Specifically:

• The two toggle buttons function differently even though they share the same visual and spacial grouping; The existing one serves as a filter display toggle, whereas the new one is a top-level filter toggle.
• The textual representation of the active filters in now split between the filter area ("Filtered by:...") and the list header ("...with an upcoming feature flag").

We can probably address both if we:

• Move the "Filtered by:..." to the header as well, and
• update the new toggle button to use the same style as the status buttons with a spelled-out label (see mockup below).

Spelling it out would also help with clarity as the flag icon is more associated with the action of flagging than the action of filtering. In the mockup above I also used the line variant instead of the filled variant, but that's only relevant if we keep the current line-variant filter icon, which leads me to my next point:

• The status filter icon is a generic filter icon even though it no longer exclusively represents the action of filtering.

To address that we could perhaps swap it out with an ellipsis that would expand the status filters immediately instead of it being a two-step interaction like it is the case today.

---

Individually these details don't amount to much, but as a whole they risk introducing a level of inconsistency and confusion around the filtering mental model, especially for people who don't use this UI frequently enough. This new addition presents an opportunity to rethink some of the earlier decisions around how filtering works, even if this is not the main focus of this PR. As it is often the case with visual design, changing tiny details often inadvertently affects the whole.

@dempseyatgithub Curious to hear your thoughts on all of the above! If time and effort required to address these is a concern, I'm happy to make whatever changes we agree on as part of this PR or even a separate one if that would make things easier.

[kaishin]

cc @krilnon @benrimmington if you have any input or insights you can share.

[dempseyatgithub]

@dempseyatgithub Curious to hear your thoughts on all of the above!

Thanks @kaishin! I really appreciate your thoughts and feedback. It's good to be able to think and talk through these issues.

The discussion in the original issue and the reply above perfectly answer the question regarding the benefit of using a standalone button. That being said doing that while leaving the previous one intact is the main source of my reluctance around this particular implementation. Specifically:

I hope I can address at least some of your reluctance.

The two toggle buttons function differently even though they share the same visual and spacial grouping;
The existing one serves as a filter display toggle, whereas the new one is a top-level filter toggle.

I may be misunderstanding what you mean by top-level toggle, but the existing filter button doesn't toggle the filter panel, it is a toggle that turns whatever status filter is set on and off.

To get the status filter panel to appear, the user needs to click the status text link next to "Filtered by:".

So, to me both buttons behave like top-level filter on/off toggles, but I may be misunderstanding your meaning.

The textual representation of the active filters in now split between the filter area ("Filtered by:...") and the list header ("...with an upcoming feature flag").

We can probably address both if we:

Move the "Filtered by:..." to the header as well

I could definitely see moving the current status filter info to the list header.

The "Filtered by: Status String" could become a link next to the filter button, something like Edit Status Filter. The words "Filtered by:" would be dropped from there and the active state of the filter button and the status text in the list header would indicate the status filter is active.

I think that could work really well.

update the new toggle button to use the same style as the status buttons with a spelled-out label (see mockup below).

Spelling it out would also help with clarity as the flag icon is more associated with the action of flagging than the action of filtering. In the mockup above I also used the line variant instead of the filled variant, but that's only relevant if we keep the current line-variant filter icon

I think we have an awkward name to try to put into a user interface, since the filter is for proposals with an Upcoming Feature Flag. I think "Feature-Flagged" ends up being not very meaningful and imprecise. Why are these features flagged? Well, the features aren't flagged, they are proposals that have flags that identify upcoming features.

Although we haven't done user testing, I think if a user clicks the flag button, and sees "5 proposals with an upcoming feature flag" in the list heading, they will know what the flag button does. That text has a link to an explanation of upcoming feature flags. The user will also see that each of those proposals has an Upcoming Feature Flag field.

So I think a single click makes it very clear what the button in the existing PR does.

In terms of using the flag icon, I think it tends to be used in two ways. One is for the user to add a flag to an item and the second is to show all items that have a flag (the second use is often in an app sidebar). In this case, the user can't add a flag to items, so only the second use applies.

So I think being precise and correct with a text button leads to an ungainly interface [Has Upcoming Feature Flag] which I don't think we should use. But I also think that any shortening makes the meaning of the text imprecise and ultimately not much more clear than the flag button.

which leads me to my next point:

The status filter icon is a generic filter icon even though it no longer exclusively represents the action of filtering.

To address that we could perhaps swap it out with an ellipsis that would expand the status filters immediately instead of it being a two-step interaction like it is the case today.

I think there are a number of examples where the filter button / icon acts on whatever is displayed at the time, even if some other narrowing has happened.

For instance, in Mail, I can click Flagged or VIP in the sidebar and then turn on the Filter button and show unread messages. In Numbers, you can hide rows in a table separately from applying a filter, so not all narrowing needs to happen in a single filter UI. I also noticed that in Numbers the Filter icon we are using is more generically called "Organize" so even it being strictly a "filter" icon is not universal.

So, I don't think it needs to be a different icon. I think the ellipsis usually means that you are going to get a menu, which wouldn't be the case.

A final concern I have with the text button is that it gives Upcoming Feature Flags a lot of emphasis in the user interface. The main con I had originally listed to the smaller flag button option was that it might give too much emphasis for UFFs.

Looking at the two options, I don't know that one is particularly more clear than the other. I think in both mockups, the user will need to click to know exactly what each button does.

For me, the two round buttons side by side are a cleaner interface, that I don't think will cause confusion.

I also think, as @kaishin suggested, that we should move the 'status string' that is currently part of the "Filtered by" element into the list header and turn that element into something like an "Edit Status Filter" link.

---

[dempseyatgithub]

@swift-ci test

[benrimmington]

Using swift-argument-parser terminology, it should be Upcoming Feature Option (🛸)!

Can I test this PR without running locally or in docker?
Otherwise, my feedback is only based on your screenshots and commits.

• Each filter button has an aria-label, but can you also add a tooltip?
• When the new filter is enabled, what is the page URL fragment?
• (The existing filter options are too tall for smaller screens.)

[dempseyatgithub]

Using swift-argument-parser terminology, it should be Upcoming Feature Option (🛸)!

Can I test this PR without running locally or in docker? Otherwise, my feedback is only based on your screenshots and commits.

I just put up a test copy.

You should be able to reach it at https://swift-test-site.xyz/swift-evolution/

• Each filter button has an aria-label, but can you also add a tooltip?

I had been wondering why the existing top-level filter button didn't have one. I had some vague recollection that tooltips were out of favor because they require hover which doesn't translate well to mobile. But yes, at least on the desktop I think they would be helpful.

The filter buttons should now have tooltips on the test version of the site.

• When the new filter is enabled, what is the page URL fragment?

It adds flags=true to the fragment. From my testing, the new fragment item interacts correctly with the existing fragments.

• (The existing filter options are too tall for smaller screens.)

That is great feedback, but would probably be a separate issue / PR.

[dempseyatgithub]

@swift-ci test

[benrimmington]

I just put up a test copy.

Thanks. I'm guessing there isn't an official staging site yet.

It adds flags=true to the fragment.

Would upcoming=true (or upcoming) be more self-explanatory?
Is it possible that "experimental" features may be included later?

From my testing, the new fragment item interacts correctly with the existing fragments.

However, search field text is ignored. For example:
https://swift-test-site.xyz/swift-evolution/#?flags=true&search=regex

[dempseyatgithub]

I just put up a test copy.

Thanks. I'm guessing there isn't an official staging site yet.

No, not yet.

It adds flags=true to the fragment.

Would upcoming=true (or upcoming) be more self-explanatory?

I think upcoming would be fine for the fragment. It definitely would be the single word in 'upcoming feature flag' that has the most meaning.

Is it possible that "experimental" features may be included later?

One dependency would be on what can be reliably parsed from Swift evolution proposals. The 'Upcoming Feature Flag' field was added to the header of the template and existing proposals updated.

I do think the audience for experimental feature flags is much smaller than for upcoming feature flags, since any Swift developer may want to adopt upcoming features and begin migrating their code immediately.

I would imagine those using an experimental feature flags would also likely be following a pitch or proposal thread in the forums. I would also imagine that once a proposal reaches review stage and appears on the dashboard, it will have its 'Upcoming Feature Flag' as part of its proposal.

From my testing, the new fragment item interacts correctly with the existing fragments.

However, search field text is ignored. For example: https://swift-test-site.xyz/swift-evolution/#?flags=true&search=regex

Thank you for catching that. I thought I had tested that. Let me see what the issue is and fix it.

[0xTim]

Great QoL improvement!

[shahmishal]

LGTM! Thanks

[dempseyatgithub]

@swift-ci test

[dempseyatgithub]

@swift-ci test

[dempseyatgithub]

The test site on https://swift-test-site.xyz/swift-evolution now reflects the latest commits:

• Filter issue fixed, the search string is no longer ignored when the UFF filter is on
• The fragment is now 'upcoming' instead of 'flags'
• Tooltips are added to the top-level filter buttons using the title attribute

After the positive feedback at the website workgroup meeting, I am going to merge the PR.

I think we should look at @kaishin's suggestion of moving the status filter string to the list header, but I think we can do that as a separate, smaller, more focused follow-on PR. I think we can also make any other additional adjustments as follow-on changes.

[kaishin]

I may be misunderstanding what you mean by top-level toggle, but the existing filter button doesn't toggle the filter panel, it is a toggle that turns whatever status filter is set on and off.
To get the status filter panel to appear, the user needs to click the status text link next to "Filtered by:".
So, to me both buttons behave like top-level filter on/off toggles, but I may be misunderstanding your meaning.

I failed to clarify what I meant by top-level, but essentially I was referring to a toggle that both applies the filter and changes its underlying value. The current button only toggles the filters—to change their value one has to click on the anchor to its left.

So I think a single click makes it very clear what the button in the existing PR does.

The feedback is immediate so it should be less of a usability issue indeed.

Regarding the choice of the icons and the presence or absence of a label, I can see now what you're going for. My only remark with regards to the example you gave is that on macOS Mail the flagged "filter" is presented as a navigation item in the sidebar, a pre-filter of sort, and not side-by-side with the filter button that acts on a list of emails. But that's not a major deal either way.

From my side, if we can address the following two items that would be ideal:

• Moving filter status to the list header and replacing the current filter text with something like "1 filter (Edit)" or similar.
• Using the outline variant of the flag icon to remain consistent with the other icon (note that macOS Mail also uses the outline version in the sidebar).

[dempseyatgithub]

From my side, if we can address the following two items that would be ideal:

• Moving filter status to the list header and replacing the current filter text with something like "1 filter (Edit)" or similar.
• Using the outline variant of the flag icon to remain consistent with the other icon (note that macOS Mail also uses the outline version in the sidebar).

I think both would be good changes.

If you have an outline variant of the flag icon ready to go or close to ready to go, that would be great.

For the filter status / filter edit link changes, maybe we should create an issue and propose specifics there?

One approach I was thinking about was listing the status in second line subhead, which would give a good amount of space. We could possible also include the version filters, since there would be a lot more breathing room.

Something like:

and

Note that those screenshots don't have any changes of the existing 'Filtered by:' link.

But again, there are a lot of possible options.