fix(core/style,best-practices,caniuse): fix stylesheet order, dedup bp-summary heading, improve caniuse a11y

src/core/best-practices.js

@@ -57,8 +57,11 @@ export function run() {
   });
   if (bps.length) {
     if (bpSummary) {
-      bpSummary.appendChild(html`<h1>Best Practices Summary</h1>`);
-      if (summaryItems) bpSummary.appendChild(summaryItems);
+      const existingHeading = bpSummary.querySelector("h2, h3, h4, h5, h6");
+      if (!existingHeading) {
+        bpSummary.prepend(html`<h1>Best Practices Summary</h1>`);
+      }
+      if (summaryItems) bpSummary.append(summaryItems);
     }
   } else if (bpSummary) {
     const msg = `Using best practices summary (#bp-summary) but no best practices found.`;

src/core/caniuse.js

@@ -195,22 +195,28 @@ function browserCellRenderer(feature) {
   return (groups, { browser: browserId, version, caniuse }) => {
     const entry = BROWSERS.get(browserId);
     const { name, type } = entry ?? { name: browserId, type: "desktop" };
-    const versionLong = version ? ` version ${version}` : "";
-    const browserName = `${name}${versionLong}`;
     const supportLevel = statToText.get(caniuse);
-    const ariaLabel = `${feature} is ${supportLevel} since ${browserName} on ${type}.`;
-    const cssClass = `caniuse-cell ${caniuse}`;
-    const title = capitalize(`${supportLevel} since ${browserName}.`);
     const textVersion = version ? version : "—";
+    const versionSuffix = version
+      ? ` version ${version}`
+      : " (version unknown)";
+    const ariaLabel = `${feature} is ${supportLevel} since ${name}${versionSuffix} on ${type}.`;
+    const cssClass = `caniuse-cell ${caniuse}`;
+    const title = capitalize(`${supportLevel} since ${name}${versionSuffix}.`);
     const src = getLogoSrc(browserId);
     const result = html`
-      <div class="${cssClass}" title="${title}" aria-label="${ariaLabel}">
+      <div
+        class="${cssClass}"
+        role="img"
+        title="${title}"
+        aria-label="${ariaLabel}"
+      >
         <img
           class="caniuse-browser"
           width="20"
           height="20"
           src="${src}"
-          alt="${name} logo"
+          alt=""
         /><span class="browser-version">${textVersion}</span>
       </div>
     `;

src/core/style.js

@@ -25,7 +25,10 @@ function insertStyle() {
   const styleElement = document.createElement("style");
   styleElement.id = "respec-mainstyle";
   styleElement.textContent = css;
-  document.head.appendChild(styleElement);
+  // Insert before any existing <link> elements so author-provided stylesheets
+  // retain their position after all ReSpec-injected styles, letting custom CSS
+  // override ReSpec defaults. insertBefore(el, null) === appendChild.
+  document.head.insertBefore(styleElement, document.head.querySelector("link"));
   return styleElement;
 }
 

tests/spec/core/best-practices-spec.js

@@ -81,4 +81,25 @@
     );
     expect(bps.querySelectorAll("ul li")).toHaveSize(3);
   });
+
+  it("does not duplicate heading when bp-summary already has one", async () => {
+    const body = `
+      <section id="bps">
+        <h2>Section</h2>
+        <span class='practicelab'>BP1</span>
+        <section id='bp-summary'>
+          <h2>Custom Heading</h2>
+        </section>
+      </section>
+    `;
+    const ops = {
+      config: makeBasicConfig(),
+      body,
+    };
+    const doc = await makeRSDoc(ops);
+    const bpSummary = doc.getElementById("bp-summary");
+    const headings = bpSummary.querySelectorAll("h2, h3, h4, h5, h6");
+    expect(headings).toHaveSize(1);
+    expect(headings[0].textContent).toBe("Custom Heading");
+  });
 });

tests/spec/core/caniuse-spec.js

@@ -103,7 +103,11 @@ describe("Core — Can I Use", () => {
 
     expect(firefox.width).toBe(20);
     expect(firefox.height).toBe(20);
-    expect(chrome.alt).toBe("Android Chrome logo");
+    expect(chrome.alt).toBe("");
+
+    // The parent cell has role=img with aria-label for accessibility
+    const firstCell = cells[0];
+    expect(firstCell.getAttribute("role")).toBe("img");
 
     // The version numbers
     const [firefoxVersion, chromeVersion, safariVersion] =
@@ -112,6 +116,12 @@ describe("Core — Can I Use", () => {
     expect(firefoxVersion.textContent).toBe("66");
     expect(safariVersion.textContent).toBe("—");
 
+    // aria-label for no-version cell uses "(version unknown)" to match visible "—"
+    const safariCell = safariVersion.closest(".caniuse-cell");
+    expect(safariCell.getAttribute("aria-label")).toBe(
+      "FEATURE is unknown support since iOS Safari (version unknown) on mobile."
+    );
+
     // More info link
     const moreInfoLink = cells.item(3);
     expect(moreInfoLink.href).toBe("https://caniuse.com/FEATURE");

tests/spec/core/custom-style.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html>
+  <meta charset="utf-8" />
+  <title>Custom Style Test</title>
+  <link rel="stylesheet" href="data:text/css," class="custom-author-style" />
+  <script class="remove">
+    var respecConfig = {
+      specStatus: "base",
+      shortName: "basics",
+    };
+  </script>
+  <section id="abstract">
+    <p>Custom style ordering test</p>
+  </section>
+  <section id="sotd">
+    <p>Test doc for verifying custom CSS insertion order.</p>
+  </section>
+</html>

tests/spec/core/style-spec.js

@@ -7,4 +7,18 @@ describe("Core — Style", () => {
     const style = doc.getElementById("respec-mainstyle");
     expect(style).toBeTruthy();
   });
+
+  it("inserts respec-mainstyle before author-provided stylesheets", async () => {
+    const doc = await makeRSDoc(
+      makeStandardOps(),
+      "spec/core/custom-style.html"
+    );
+    const respecStyle = doc.getElementById("respec-mainstyle");
+    const authorLink = doc.querySelector("link.custom-author-style");
+    expect(respecStyle).toBeTruthy();
+    expect(authorLink).toBeTruthy();
+    // Bitmask: Node.DOCUMENT_POSITION_FOLLOWING = 4 means respecStyle comes before authorLink
+    const position = respecStyle.compareDocumentPosition(authorLink);
+    expect(position & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  });
 });