Infrastructure: Add special Treatment of Examples Marked 'Experimental'

[alflennik]

Adds special treatment of examples that are marked 'experimental' as described in #2836.

This PR is currently using fake experimental content and should not be merged until content developed to resolve #3015 is merged into this branch.

The build can be previewed here:
https://deploy-preview-310--aria-practices.netlify.app/aria/apg/

Because this is a new content type, the automatic build will not work until the accompanying wai-aria-practices PR 310 is merged.

---

WAI Preview Link (Last built on Sun, 28 Jul 2024 01:10:31 GMT).

[alflennik]

@howard-e do you know why the tests are failing? The failures do not seem related to the changes in the PR. I tried a few retries but that didn't seem to help.

[alflennik]

Hi @mcking65! If you could take a look at the experimental support notice copy, I'm sure you will have a few changes to recommend!

[howard-e]

@howard-e do you know why the tests are failing? The failures do not seem related to the changes in the PR. I tried a few retries but that didn't seem to help.

@alflennik you are right that the failure has nothing to do with this PR.

It is the same issue reported in #2938. I haven't spent the time to investigate why it happens but it is being tracked in the APG's issue triaging process process so your work here should be able to continue with that in mind.

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed Support for experimental content.

The full IRC log of that discussion

<jugglinmike> Topic: Support for experimental content
<jugglinmike> github: https://github.com//pull/2977
<jugglinmike> Matt_King: If you follow the preview link, then go to the "index" page and scroll down so you have the very last heading on the page in view
<jugglinmike> Matt_King: It's called "experimental examples"
<jugglinmike> Matt_King: The first pattern we want to get into APG is called "ARIA Actions"
<jugglinmike> Matt_King: We want people to be able to get to ARIA Actions--the people who are working on this, e.g. ARIA-AT Testers
<jugglinmike> Matt_King: Those people will be able to pull up this example which is "not part of the official APG"
<jugglinmike> Matt_King: There are several aspects to the design of this page
<jugglinmike> Matt_King: Every experimental example's title has the word "Experimental" in brackets
<jugglinmike> Matt_King: The "read this first" content is expanded by default (instead of being collapsed by default)
<jugglinmike> Matt_King: And the "About this example" section instead read "About this experimental example"
<jugglinmike> Matt_King: all of these things would change when the example stops being experimental
<jugglinmike> Matt_King: But we won't do this in the pattern itself. It's kind of hidden. Not totally hidden, but kind of
<jugglinmike> Matt_King: My question for the group: Is this design sufficient to make sure people understand that this is experimental?
<jugglinmike> Jem: This is great. I remember talking about this at TPAC. There, I mentioned that I wanted to see a reference to ARIA to help explain why we are experimenting here in APG
<jugglinmike> Jem: I think we're missing that context at the moment
<jugglinmike> Matt_King: We would address that in the "About this example" section by adding a link to the draft
<jugglinmike> Jem: I have some thoughts about the wording of the description
<jugglinmike> Matt_King: I'm still working on the wording; I'm mostly just looking for feedback to the high-level changes (The title, the heading, etc.)
<jugglinmike> Matt_King: At the point in time that it becomes evergreen in ARIA, we would have a pull request that removes the word "experimental" everywhere it shows up, we would remove the metadata that causes it to be listed separately in the index
<jugglinmike> Jem: I like that. I like that we'll be able to prepare for the transition to take place when the time is right
<jugglinmike> jongund: I think it looks good. It seems pretty clear that it's experimental. The word is everywhere
<jugglinmike> jongund: I agree with Jem's feedback to highlight the relationship to the draft spec
<jugglinmike> Bryan_Garaventa: Does it explain what the term "experimental" means?
<jugglinmike> Matt_King: yes
<jugglinmike> Matt_King: I'm going to take this to the next level by updating some of the content. Is that going to be a problem for Alex?
<jugglinmike> howard-e: That should be fine
<jugglinmike> howard-e: Should this be excluded from updating the "coverage and quality" report?
<jugglinmike> Matt_King: I actually think that no, it should not be excluded, for two reasons. I think it would be good to be able to see if the experimental pages cause any quality problems.
<jugglinmike> Matt_King: Second, even if people outside of the APG Task Force look at the report, I think the title of these pages will make it clear to them that these are experimental.

[howard-e]

@alflennik code seems good to me, well done on this! I've left questions inline below but they are non-blocking thoughts.

This also needs a merge with main to resolve the new merge conflicts.

[howard-e]

@howard-e do you know why the tests are failing? The failures do not seem related to the changes in the PR. I tried a few retries but that didn't seem to help.

@alflennik you are right that the failure has nothing to do with this PR.

It is the same issue reported in #2938. I haven't spent the time to investigate why it happens but it is being tracked in the APG's issue triaging process process so your work here should be able to continue with that in mind.

@alflennik while reviewing some other PRs, realized I was wrong with my initial statement. It was still a flaky build error but not the issue I originally linked.

I submitted #2996 to reflect the actual failing test that's here and I've also pushed #2997 which should address it.

[stalgiag]

Seems that the cheerio.remove() leaves a blank line behind. Reviewers can let me know if I should find an alternate solution for removal.

[howard-e]

This seems like a small enough detail that shouldn't affect anything, so it can be ignored, but thanks for pointing that out!

[howard-e]

@alflennik @stalgiag thanks for working on this, seems great! Verified this should allow for experimental content to be included and removed in the future once drafted.

This PR references w3c/wai-aria-practices#310 being merged as well first but it also has the example that will no longer be used, so that content will have to be updated too.

[howard-e]

@mcking65 the supporting build change for this PR has now been merged at w3c/wai-aria-practices#310, so this PR's preview link should now show any experimental content drafted for aria-actions.