Add a Specifications macro and extract a special specification sectio…

…n to the Document (mdn#3518)

* Prototype spec section from BCD spec_urls

* Address some feedback, mostly rename things

* Branch out building special sections in their own functions per Ryuno-Ki

* Add a KumaScript test

* Add extraction test

* Add browser-specs data; update tests; update renderer

* feedback on pr 3518

* Remove log calls, fix tests

* Rename SpecificationTable to SpecificationSection/Specifications

* Update browser-specs to latest

* Add specfications to makeTOC

* Move spec-section to ingredients

* Remove comment

Co-authored-by: Peter Bengtsson <[email protected]>

build/index.js

@@ -212,7 +212,8 @@ function makeTOC(doc) {
     .map((section) => {
       if (
         (section.type === "prose" ||
-          section.type === "browser_compatibility") &&
+          section.type === "browser_compatibility" ||
+          section.type === "specifications") &&
         section.value.id &&
         section.value.title &&
         !section.value.isH3

client/src/document/index.tsx

@@ -9,6 +9,7 @@ import { Doc } from "./types";
 // Ingredients
 import { Prose, ProseWithHeading } from "./ingredients/prose";
 import { LazyBrowserCompatibilityTable } from "./lazy-bcd-table";
+import { SpecificationSection } from "./ingredients/spec-section";
 
 // Misc
 // Sub-components
@@ -232,6 +233,10 @@ function RenderDocumentBody({ doc }) {
           {...section.value}
         />
       );
+    } else if (section.type === "specifications") {
+      return (
+        <SpecificationSection key={`specifications${i}`} {...section.value} />
+      );
     } else {
       console.warn(section);
       throw new Error(`No idea how to handle a '${section.type}' section`);

client/src/document/ingredients/spec-section.tsx

@@ -0,0 +1,64 @@
+import { DisplayH2, DisplayH3 } from "./utils";
+
+export function SpecificationSection({
+  id,
+  title,
+  isH3,
+  specifications,
+  query,
+}: {
+  id: string;
+  title: string;
+  isH3: boolean;
+  specifications: Array<{
+    title: string;
+    bcdSpecificationURL: string;
+    shortTitle: string;
+  }>;
+  query: string;
+}) {
+  return (
+    <>
+      {title && !isH3 && <DisplayH2 id={id} title={title} />}
+      {title && isH3 && <DisplayH3 id={id} title={title} />}
+
+      {specifications.length > 0 ? (
+        <table className="standard-table">
+          <thead>
+            <tr>
+              <th scope="col">Specification</th>
+            </tr>
+          </thead>
+          <tbody>
+            {specifications.map((spec) => (
+              <tr key={spec.bcdSpecificationURL}>
+                <td>
+                  <a href={spec.bcdSpecificationURL}>
+                    {spec.title} ({spec.shortTitle})
+                    <br />{" "}
+                    <small>#{spec.bcdSpecificationURL.split("#")[1]}</small>
+                  </a>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      ) : (
+        <div className="notecard warning">
+          <h4>No specification found</h4>
+          <p>
+            No specification data found for <code>{query}</code>.<br />
+            <a href="#on-github">Check for problems with this page</a> or
+            contribute a missing <code>spec_url</code> to{" "}
+            <a href="https://github.com/mdn/browser-compat-data">
+              mdn/browser-compat-data
+            </a>
+            . Also make sure the specification is included in{" "}
+            <a href="https://github.com/w3c/browser-specs">w3c/browser-specs</a>
+            .
+          </p>
+        </div>
+      )}
+    </>
+  );
+}

kumascript/macros/Specifications.ejs

@@ -0,0 +1,25 @@
+<%
+/*
+Placeholder to render a specification section with spec_urls from BCD
+
+Parameters
+
+$0 – A query string indicating for which feature to retrieve specification URLs for.
+
+Example calls
+
+{{Specifications}}
+{{Specifications("html.element.abbr")}}
+
+*/
+
+var query = $0 || env['browser-compat'];
+if (!query) {
+  throw new Error("No first query argument or 'browser-compat' front-matter value passed");
+}
+var output = `<div class="bc-specs" data-bcd-query="${query}">
+  If you're able to see this, something went wrong on this page.
+</div>`;
+%>
+
+<%-output%>

kumascript/tests/macros/Specifications.test.js

@@ -0,0 +1,24 @@
+const { assert, itMacro, describeMacro, lintHTML } = require("./utils");
+
+const jsdom = require("jsdom");
+const { JSDOM } = jsdom;
+
+describeMacro("Specifications", function () {
+  itMacro("Outputs a simple div tag", async (macro) => {
+    const result = await macro.call("api.feature");
+    const dom = JSDOM.fragment(result);
+    assert.equal(
+      dom.querySelector("div.bc-specs").dataset.bcdQuery,
+      "api.feature"
+    );
+    assert.equal(
+      dom.querySelector("div.bc-specs").textContent.trim(),
+      "If you're able to see this, something went wrong on this page."
+    );
+  });
+
+  itMacro("Outputs valid HTML", async (macro) => {
+    const result = await macro.call("api.feature");
+    expect(lintHTML(result)).toBeFalsy();
+  });
+});

package.json

@@ -43,6 +43,7 @@
     "@fast-csv/parse": "4.3.6",
     "@mdn/browser-compat-data": "3.3.2",
     "accept-language-parser": "1.5.0",
+    "browser-specs": "^1.34.2",
     "chalk": "4.1.1",
     "cheerio": "1.0.0-rc.6",
     "cli-progress": "^3.9.0",

testing/content/files/en-us/web/spec_section_extraction/index.html

@@ -0,0 +1,20 @@
+---
+title: Spec section extraction
+browser-compat: javascript.builtins.Array.toLocaleString
+slug: Web/Spec_Section_Extraction
+---
+
+<h2>Intro</h2>
+<p>Text in Intro</p>
+
+<h2 id="Specifications">Specifications</h2>
+
+<p>{{Specifications}}</p>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<p>{{Compat}}</p>
+
+<h2 id="See_also">See also</h2>
+
+<p>More stuff</p>

testing/tests/index.test.js

@@ -1056,6 +1056,34 @@ test("bcd table extraction followed by h3", () => {
   expect(doc.body[4].value.isH3).toBeTruthy();
 });
 
+test("specifications and bcd extraction", () => {
+  const builtFolder = path.join(
+    buildRoot,
+    "en-us",
+    "docs",
+    "web",
+    "spec_section_extraction"
+  );
+  expect(fs.existsSync(builtFolder)).toBeTruthy();
+  const jsonFile = path.join(builtFolder, "index.json");
+  const { doc } = JSON.parse(fs.readFileSync(jsonFile));
+  expect(doc.body[0].type).toBe("prose");
+  expect(doc.body[1].type).toBe("specifications");
+  expect(doc.body[1].value.specifications[0].shortTitle).toBe("ECMAScript");
+  expect(doc.body[1].value.specifications[0].bcdSpecificationURL).toBe(
+    "https://tc39.es/ecma262/#sec-array.prototype.tolocalestring"
+  );
+  expect(doc.body[1].value.specifications[1].shortTitle).toBe(
+    "ECMAScript Internationalization API"
+  );
+  expect(doc.body[1].value.specifications[1].bcdSpecificationURL).toBe(
+    "https://tc39.es/ecma402/#sup-array.prototype.tolocalestring"
+  );
+  expect(doc.body[2].type).toBe("prose");
+  expect(doc.body[3].type).toBe("browser_compatibility");
+  expect(doc.body[4].type).toBe("prose");
+});
+
 test("headers within non-root elements is a 'sectioning' flaw", () => {
   const builtFolder = path.join(
     buildRoot,

yarn.lock

@@ -5864,6 +5864,11 @@ browser-process-hrtime@^1.0.0:
   resolved "https://registry.yarnpkg.com/browser-process-hrtime/-/browser-process-hrtime-1.0.0.tgz#3c9b4b7d782c8121e56f10106d84c0d0ffc94626"
   integrity sha512-9o5UecI3GhkpM6DrXr69PblIuWxPKk9Y0jHBRhdocZ2y7YECBFCsHm79Pr3OyR2AvjhDkabFJaDJMYRazHgsow==
 
+browser-specs@^1.34.2:
+  version "1.35.1"
+  resolved "https://registry.yarnpkg.com/browser-specs/-/browser-specs-1.35.1.tgz#01c77221940b5d733995248438e869ca5342cc9c"
+  integrity sha512-y9rMHjHa2kXUOBqovbRHCQAQhCJARiPQYluiO3PBoBl4Wa7f0ukE72+zDBN7+0oYzdRyWngZaUtl2rqCVdZ1Aw==
+
 browserify-aes@^1.0.0, browserify-aes@^1.0.4:
   version "1.2.0"
   resolved "https://registry.yarnpkg.com/browserify-aes/-/browserify-aes-1.2.0.tgz#326734642f403dabc3003209853bb70ad428ef48"