Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Infrastructure: Add special Treatment of Examples Marked 'Experimental' #2977

Merged
merged 10 commits into from
Jul 28, 2024
Merged

Infrastructure: Add special Treatment of Examples Marked 'Experimental' #2977

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
754b240
Add experimental content (issue 2836)
alflennik Mar 27, 2024
7f418ef
Fix formatting for sample experimental content
alflennik Mar 27, 2024
4910303
Relabel experimental usage warning
alflennik Mar 27, 2024
2c2869c
Add required attribute for experimental content
alflennik Mar 27, 2024
c5171aa
Merge branch 'main' into experimental-content
stalgiag Jun 10, 2024
9ee1942
Remove experimental placeholder data
stalgiag Jun 10, 2024
d4e4c32
Only render experimental examples section when experimental examples …
stalgiag Jun 10, 2024
e793398
Remove the link to experimental examples section when no experimental…
stalgiag Jun 10, 2024
166b9fc
Merge remote-tracking branch 'origin/main' into experimental-content
mcking65 Jul 28, 2024
29dcab3
Editorial revisions to experimental content warning.update coverage r…
mcking65 Jul 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions content/index/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ <h2>About the Index</h2>
<ul>
<li><a href="#examples_by_role_label">Examples by Role</a></li>
<li><a href="#examples_by_props_label">Examples by Properties and States</a></li>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

</ul>
<section id="examples_by_roles">
<h2 id="examples_by_role_label">Examples by Role</h2>
Expand Down Expand Up @@ -903,6 +904,7 @@ <h2 id="examples_by_props_label">Examples By Properties and States</h2>
</tr></tbody>
</table>
</section>

</main>


Expand Down
14 changes: 10 additions & 4 deletions content/shared/js/app.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,20 @@
// Determine we are on an example page
if (!document.location.href.match(/examples\/[^/]+\.html/)) return;

const isExperimental =
document.querySelector('main')?.getAttribute('data-content-phase') ===
'experimental';

const usageWarningLink = isExperimental
? '/templates/experimental-example-usage-warning.html'
: '/templates/example-usage-warning.html';

// Generate the usage warning link using app.js link as a starting point
const scriptSource = document
.querySelector('[src$="app.js"]')
.getAttribute('src');
const fetchSource = scriptSource.replace(
'/js/app.js',
'/templates/example-usage-warning.html'
);

const fetchSource = scriptSource.replace('/js/app.js', usageWarningLink);

// Load and parse the usage warning and insert it before the h1
const html = await (await fetch(fetchSource)).text();
Expand Down
30 changes: 30 additions & 0 deletions content/shared/templates/experimental-example-usage-warning.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<!DOCTYPE html>
<html lang="en">
<meta charset="utf-8">
<title>Experimental Support Notice (Template)</title>
<body>
<h2 id="support-notice-header">Read This First</h2>
<details id="support-notice" open>
<summary>
The code in this example is experimental and should therefore be considered incomplete, potentially unreliable and subject to change without notice.
Please read below to understand why.
</summary>
<p>This is an experimental example of one way of using ARIA that may or may not conform with the current ARIA specification.</p>
<ul>
<li>Experimental content is not final and is published to facilitate discussion and gather feedback, but it should not considered as authoritative as other content in the ARIA Authoring Practices Guide.</li>
<li>
There may be support gaps in some
<a href="../../practices/read-me-first/read-me-first-practice.html#browser_and_AT_support">browser and assistive technology combinations</a>,
especially for
<a href="../../practices/read-me-first/read-me-first-practice.html#mobile_and_touch_support">mobile/touch devices</a>.
Testing code based on this example with assistive technologies is essential before considering use in production systems.
</li>
<li>The <a href="https://aria-at.w3.org">ARIA and Assistive Technologies Project</a> is developing measurements of assistive technology support for APG examples.</li>
<li>
Robust accessibility can be further optimized by choosing implementation patterns that <a href="https://www.w3.org/TR/using-aria/#rule1">maximize use of semantic HTML</a> and heeding the warning that
<a href="../../practices/read-me-first/read-me-first-practice.html#no_aria_better_bad_aria">No ARIA is better than Bad ARIA</a>.
</li>
</ul>
</details>
</body>
</html>
30 changes: 28 additions & 2 deletions scripts/reference-tables.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,7 @@ const ariaPropertiesAndStates = [

let indexOfRoles = {};
let indexOfPropertiesAndStates = {};
const indexOfExperimentalContent = [];

console.log('Generating index...');

Expand Down Expand Up @@ -209,6 +210,10 @@ function getPropertiesAndStates(html) {
return propertiesAndStates;
}

function addExampleToExperimentalContent(example) {
indexOfExperimentalContent.push(example);
}

function addExampleToRoles(roles, example) {
for (let i = 0; i < roles.length; i++) {
let role = roles[i];
Expand Down Expand Up @@ -268,6 +273,10 @@ glob

let html = HTMLParser.parse(data);

const isExperimental =
html.querySelector('main')?.getAttribute('data-content-phase') ===
'experimental';

let ref = file.replace('content', '..');
let title = html
.querySelector('title')
Expand All @@ -283,8 +292,12 @@ glob
highContrast: data.toLowerCase().indexOf('high contrast') > 0,
};

addExampleToRoles(getRoles(html), example);
addExampleToPropertiesAndStates(getPropertiesAndStates(html), example);
if (isExperimental) {
addExampleToExperimentalContent(example);
} else {
addExampleToRoles(getRoles(html), example);
addExampleToPropertiesAndStates(getPropertiesAndStates(html), example);
}
});

// Add landmark examples, since they are a different format
Expand Down Expand Up @@ -390,6 +403,19 @@ let examplesByProps = sortedPropertiesAndStates.reduce(function (set, prop) {
</tr>`;
}, '');

const examplesExperimental = indexOfExperimentalContent
.map(exampleListItem)
.join('');

if (examplesExperimental.length === 0) {
// Do no display the experimental section if there are no experimental examples
$('#examples_experimental').remove();
// Remove the <li> element containing the link to Experimental Examples
$('a[href="#examples_experimental_label"]').parent().remove();
} else {
$('#examples_experimental_ul').html(examplesExperimental);
}

$('#examples_by_props_tbody').html(examplesByProps);

// cheerio seems to fold the doctype lines despite the template
Expand Down
8 changes: 8 additions & 0 deletions scripts/reference-tables.template
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
<ul>
<li><a href="#examples_by_role_label">Examples by Role</a></li>
<li><a href="#examples_by_props_label">Examples by Properties and States</a></li>
<li><a href="#examples_experimental_label">Experimental Examples</a></li>
</ul>
<section id="examples_by_roles">
<h2 id="examples_by_role_label">Examples by Role</h2>
Expand Down Expand Up @@ -52,6 +53,13 @@
</tbody>
</table>
</section>
<section id="examples_experimental">
<h2 id="examples_experimental_label">Experimental Examples</h2>
<div><strong>NOTE:</strong> The HC abbreviation means example has High Contrast support.</div>
<ul id="examples_experimental_ul">

</ul>
</section>
stalgiag marked this conversation as resolved.
Show resolved Hide resolved
</main>
</body>
</html>
Loading