Infrastructure: Add special Treatment of Examples Marked 'Experimenta…

…l' (pull #2977) Provides the infrastructure to treat example pages marked as experimental differently from other example pages as defined in issue #2836: 1. A different "Read This First" section that is expanded by default is inserted into experimental example pages. 2. Experimental example pages are excluded from the main index tables and listed in a separate section at the bottom of the index page. Experimental example pages are identified by a data attribute on the main element as defined in issue #2836. --------- Co-authored-by: Stalgia Grigg <[email protected]> Co-authored-by: Matt King <[email protected]>
w3c · Jul 28, 2024 · 2a2e148 · 2a2e148
1 parent 1637413
commit 2a2e148
Show file tree

Hide file tree

Showing 5 changed files with 72 additions and 6 deletions.
diff --git a/content/index/index.html b/content/index/index.html
@@ -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>
+
     </ul>
     <section id="examples_by_roles">
       <h2 id="examples_by_role_label">Examples by Role</h2>
@@ -903,6 +904,7 @@ <h2 id="examples_by_props_label">Examples By Properties and States</h2>
           </tr></tbody>
       </table>
     </section>
+
   </main>
 
 

diff --git a/content/shared/js/app.js b/content/shared/js/app.js
@@ -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();

diff --git a/content/shared/templates/experimental-example-usage-warning.html b/content/shared/templates/experimental-example-usage-warning.html
@@ -0,0 +1,24 @@
+<!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>
+        Experimental content! Do not use except for new standards development purposes.
+        Please read below to understand why.
+      </summary>
+      <p>This is an experimental implementation of potential future techniques that may not yet be supported by web standards.</p>
+      <ul>
+        <li> This example may include ARIA, HTML, CSS, or other code that is not yet included in a final web standard specification. </li>
+        <li>Experimental content is published in the APG only to facilitate discussion, gather feedback, and support testing of new features in browsers and assistive technologies.</li>
+        <li>
+          There may be little or no support for this example in any or most
+          <a href="../../practices/read-me-first/read-me-first-practice.html#browser_and_AT_support">browser and assistive technology combinations</a>.
+        </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>
+      </ul>
+    </details>
+  </body>
+</html>
diff --git a/scripts/reference-tables.js b/scripts/reference-tables.js
@@ -161,6 +161,7 @@ const ariaPropertiesAndStates = [
 
 let indexOfRoles = {};
 let indexOfPropertiesAndStates = {};
+const indexOfExperimentalContent = [];
 
 console.log('Generating index...');
 
@@ -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];
@@ -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')
@@ -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
@@ -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

diff --git a/scripts/reference-tables.template b/scripts/reference-tables.template
@@ -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>
@@ -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>
   </main>
 </body>
 </html>