Implement client-side filtering for previews (#351)

Author: kfranqueiro

src/components/guidelines/Guidelines.astro

@@ -15,7 +15,12 @@ const groups = await buildGuidelinesHierarchy();
           <h4>{computeTitle(guideline)}</h4>
           <EntryText entry={guideline} />
           {guideline.data.requirements.map((requirement) => (
-            <section class="requirement" data-status={requirement.data.status} data-requirement-type={requirement.data.type}>
+            <section
+              class="requirement"
+              data-status={requirement.data.status}
+              data-requirement-type={requirement.data.type}
+              data-skip={requirement.skippable}
+            >
               <h5>{computeTitle(requirement)}</h5>
               <EntryText entry={requirement} />
             </section>

src/components/respec/GuidelinesRespec.astro

@@ -1,4 +1,7 @@
 ---
+import { isDevOrPreview } from "@/lib/constants";
+import GuidelinesRespecDev from "./GuidelinesRespecDev.astro";
+
 // ReSpec config and functions are defined in a component with an inline script to allow
 // separating them in a way that will be conducive to sending to spec-generator, while
 // avoiding Vite warnings which may occur when referencing scripts under public/
@@ -449,13 +452,15 @@
         href: "https://www.etsi.org/deliver/etsi_tr/101500_101599/101550/01.01.01_60/tr_101550v010101p.pdf",
       },
       "iso13066-1": {
-          "href": "https://www.iso.org/standard/53770.html",
-          "title": "Information technology — Interoperability with assistive technology (AT) - Part 1: Requirements and recommendations for interoperability",
-          "status": "Published",
-          "publisher": "ISO/IEC",
-          "isoNumber": "ISO 13066-1:2011",
-          "rawDate": "2011-05"
+        href: "https://www.iso.org/standard/53770.html",
+        title:
+          "Information technology — Interoperability with assistive technology (AT) - Part 1: Requirements and recommendations for interoperability",
+        status: "Published",
+        publisher: "ISO/IEC",
+        isoNumber: "ISO 13066-1:2011",
+        rawDate: "2011-05",
       },
     },
   };
 </script>
+{isDevOrPreview && <GuidelinesRespecDev />}

src/components/respec/GuidelinesRespecDev.astro

@@ -0,0 +1,25 @@
+<script is:inline>
+  function filterSkippable() {
+    const params = new URLSearchParams(location.search);
+    if (params.get("skip")) document.querySelectorAll("[data-skip]").forEach((el) => el.remove());
+  }
+  respecConfig.preProcess.push(filterSkippable);
+
+  function addSkipUI() {
+    const newUrl = new URL(location);
+    if (newUrl.searchParams.get("skip")) newUrl.searchParams.delete("skip");
+    else newUrl.searchParams.set("skip", "true");
+
+    const respecEl = document.getElementById("respec-ui");
+    const el = document.createElement("a");
+    el.href = "" + newUrl;
+    el.style.position = "fixed";
+    el.style.top = "60px";
+    el.style.right = getComputedStyle(respecEl).right;
+    el.textContent = newUrl.searchParams.get("skip")
+      ? "Preview without early-stage entries"
+      : "Preview with all entries";
+    respecEl.after(el);
+  }
+  respecConfig.postProcess.push(addSkipUI);
+</script>

src/lib/constants.ts

@@ -0,0 +1,2 @@
+/** Indicates that the build is running in a dev or PR preview environment. */
+export const isDevOrPreview = !!import.meta.env.DEV || !!import.meta.env.NETLIFY;

src/lib/guidelines.ts

@@ -1,37 +1,49 @@
 import { getCollection, getEntry, type CollectionEntry, type CollectionKey } from "astro:content";
 import capitalize from "lodash-es/capitalize";
+import difference from "lodash-es/difference";
+
+import { isDevOrPreview } from "./constants";
 
 /**
- * Returns a filtered list of requirement/assertion slugs under the given group and guideline,
- * excluding any marked as needing additional research if WCAG_SKIP_WIP is set.
+ * Returns a list of requirement/assertion slugs under the given group and guideline that would be
+ * skipped for a major publication (i.e. exploratory/placeholder or needs additional research).
+ * Note this returns an empty array when building for situations that do not allow for skipping
+ * either at build time or client-side (e.g. Editor's Drafts).
  */
-async function getFilteredRequirements(groupId: string, guidelineSlug: string) {
+async function determineSkippableRequirements(groupId: string, guidelineSlug: string) {
+  // Only populate when running a build that needs to skip at build time or client-side
+  if (!import.meta.env.WCAG_SKIP_WIP && !isDevOrPreview) return [];
+
   const guideline = await getEntry("guidelines", `${groupId}/${guidelineSlug}`);
   if (!guideline) throw new Error(`Unresolvable guideline ID: ${guidelineSlug}`);
 
-  const filteredRequirements: string[] = [];
+  const skippableRequirements: string[] = [];
   for (const requirementSlug of guideline.data.children) {
     const requirement = await getEntry(
       "requirements",
       `${groupId}/${guidelineSlug}/${requirementSlug}`
     );
     if (!requirement) throw new Error(`Unresolvable requirement ID: ${requirementSlug}`);
     if (
-      import.meta.env.WCAG_SKIP_WIP &&
-      (requirement.data.needsAdditionalResearch ||
-        requirement.data.status === "placeholder" ||
-        requirement.data.status === "exploratory")
-    )
-      continue;
-    filteredRequirements.push(requirementSlug);
+      requirement.data.needsAdditionalResearch ||
+      requirement.data.status === "placeholder" ||
+      requirement.data.status === "exploratory"
+    ) {
+      skippableRequirements.push(requirementSlug);
+    }
   }
-  return filteredRequirements;
+  return skippableRequirements;
+}
+
+/** Extension of Requirement to facilitate client-side skipping in previews */
+interface SkippableRequirement extends CollectionEntry<"requirements"> {
+  skippable?: boolean;
 }
 
 let groupIds = (await getCollection("groupOrder")).map(({ id }) => id);
 let groups: Record<string, CollectionEntry<"groups">> = {};
 let guidelines: Record<string, CollectionEntry<"guidelines">> = {};
-let requirements: Record<string, CollectionEntry<"requirements">> = {};
+let requirements: Record<string, SkippableRequirement> = {};
 
 export async function buildGuidelinesHierarchy() {
   // Cache collated collection data for subsequent calls
@@ -44,16 +56,22 @@ export async function buildGuidelinesHierarchy() {
       for (const guidelineSlug of group.data.children) {
         const guideline = await getEntry("guidelines", `${groupId}/${guidelineSlug}`);
         if (!guideline) throw new Error(`Unresolvable guideline ID: ${guidelineSlug}`);
-        guideline.data.children = await getFilteredRequirements(groupId, guidelineSlug);
         guidelines[guideline.id] = guideline;
 
+        const skippableChildren = await determineSkippableRequirements(groupId, guidelineSlug);
+        if (import.meta.env.WCAG_SKIP_WIP)
+          // Filter children directly in case of build-time skip
+          guideline.data.children = difference(guideline.data.children, skippableChildren);
+
         for (const requirementSlug of guideline.data.children) {
           const requirement = await getEntry(
             "requirements",
             `${groupId}/${guidelineSlug}/${requirementSlug}`
           );
           if (!requirement) throw new Error(`Unresolvable requirement ID: ${requirementSlug}`);
-          requirements[requirement.id] = requirement;
+          requirements[requirement.id] = skippableChildren.includes(requirementSlug)
+            ? { ...requirement, skippable: true }
+            : requirement;
         }
       }
     }