Improve wrapper handling for how-to links (#330)

Author: kfranqueiro

src/components/guidelines/EntryText.astro

@@ -1,9 +1,9 @@
 ---
-import { z, type CollectionEntry } from "astro:content";
+import { type CollectionEntry } from "astro:content";
 
 import { computeTitle } from "@/lib/guidelines";
-import { renderAndValidate } from "@/lib/zod";
 import { getEntry } from "astro:content";
+import { load } from "cheerio";
 
 interface Props {
   entry: CollectionEntry<"guidelines"> | CollectionEntry<"requirements">;
@@ -20,40 +20,44 @@ const howtoPath = parentHowto
   ? `${parentHowto === true ? idParts[1] : parentHowto}/${howtoSlug}/`
   : `${howtoSlug}/`;
 const baseUrl = "https://w3c.github.io/wcag3/how-to/";
-const { Content, remarkPluginFrontmatter } = await renderAndValidate(
-  entry,
-  z.object({
-    description: z.string(),
-  })
-);
----
 
-{
-  howtoSlug ? (
-    <div class="body-wrapper">
-      <Fragment set:html={remarkPluginFrontmatter.description} />
-      <aside class="doclinks">
-        <p>
-          <a href={`${baseUrl}${howtoPath}`}>
-            <svg aria-hidden="true" class="i-info">
-              <use xlink:href="img/icons.svg#i-info" />
-            </svg>{" "}
-            {entry.collection === "guidelines"
+function processHtml() {
+  const entryHtml = entry.rendered!.html;
+  if (!howtoSlug) return entryHtml;
+
+  const $ = load(entryHtml, null, false);
+  const $wrappableElement = $("p, ul, ol")
+    // Exclude nested elements (e.g. inside of a Note)
+    .filter((_, el) => !$(el).parent().length)
+    .first();
+  if (!$wrappableElement.length)
+    throw new Error(`${entry.id}: Can't find element to wrap with link to how-tos`);
+
+  $wrappableElement.wrap(`<div class="body-wrapper"></div>`).after(`
+    <aside class="doclinks">
+      <p>
+        <a href="${baseUrl}${howtoPath}">
+          <svg aria-hidden="true" class="i-info">
+            <use xlink:href="img/icons.svg#i-info" />
+          </svg>
+          ${
+            entry.collection === "guidelines"
               ? `How to meet ${computeTitle(entry)}`
-              : `${computeTitle(entry)} methods`}
-          </a>
-        </p>
-      </aside>
-    </div>
-  ) : (
-    <Fragment set:html={remarkPluginFrontmatter.description} />
-  )
+              : `${computeTitle(entry)} methods`
+          }
+        </a>
+      </p>
+    </aside>
+  `);
+  return $.html();
 }
+---
+
 {
   entry.collection === "requirements" && entry.data.needsAdditionalResearch && (
     <p class="ednote">
       Needs <a href="#additional_research">additional research</a>
     </p>
   )
 }
-<Content />
+<Fragment set:html={processHtml()} />

src/lib/markdown/guidelines.ts

@@ -1,7 +1,5 @@
-import type { RehypePlugin, RemarkPlugin } from "@astrojs/markdown-remark";
-import type { RootContent } from "hast";
+import type { RemarkPlugin } from "@astrojs/markdown-remark";
 
-import { toHtml } from "hast-util-to-html";
 import { visit } from "unist-util-visit";
 import type { VFile } from "vfile";
 
@@ -76,33 +74,5 @@ const customDirectives: RemarkPlugin = () => (tree, file) => {
   });
 };
 
-/** Extracts leading paragraphs/lists' HTML to a separate value. */
-const extractLeadingContent: RehypePlugin = () => (tree, file) => {
-  if (!isGuidelineFile(file)) return;
-  const contentTags = ["p", "ul", "ol"];
-  const leadingElements: RootContent[] = [];
-  const textClass = `${getGuidelineFileType(file)}-text`;
-
-  for (
-    let child = tree.children[0];
-    child?.type === "text" || (child?.type === "element" && contentTags.includes(child.tagName));
-    tree.children.shift() && (child = tree.children[0])
-  ) {
-    if (child.type === "element") {
-      const existingClass = child.properties.class;
-      if (existingClass) child.properties.class += ` ${textClass}`;
-      else child.properties.class = textClass;
-    }
-    leadingElements.push(child);
-  }
-  if (!leadingElements.length) file.fail("Leading content expected but not found.");
-
-  const html = toHtml(leadingElements, {
-    allowDangerousCharacters: true,
-    allowDangerousHtml: true,
-  });
-  getFrontmatter(file).description = html;
-};
-
 export const guidelinesRemarkPlugins = [addEmptyTermNote, customDirectives];
-export const guidelinesRehypePlugins = [extractLeadingContent];
+export const guidelinesRehypePlugins = [];

src/styles/guidelines.css

@@ -63,6 +63,11 @@ a.internalDFN[title]:hover, .internalDFN[title]:active, a.internalDFN[title]:foc
 	color: #404040;
 }
 
+:is(.guideline, .requirement, .body-wrapper) > :is(p, ul, ol) {
+	font-size: 110%;
+	margin-top: 0;
+}
+
 .guideline {
 	margin-left: 4em;
 	position: relative;
@@ -73,10 +78,6 @@ a.internalDFN[title]:hover, .internalDFN[title]:active, a.internalDFN[title]:foc
 	position: relative;
 }
 
-.guideline-text, .requirement-text {
-	font-size: 110%;
-	margin-top: 0;
-}
 .guideline h3, .requirement h4, .requirement h5 {
 	width: 100%;
 	margin-bottom: 0;