reffy 6.2.0 → 6.2.1

package/src/browserlib/extract-elements.mjs

@@ -1,205 +1,205 @@
-/**
- * Extract the list of markup elements that the spec defines
- *
- * Extraction requires spec to follow a structure similar to the one used in
- * the HTML spec:
- * https://html.spec.whatwg.org/multipage/dom.html#element-definitions
- *
- * Important (2021-05-31): Extraction code is incomplete and only extracts the
- * mapping between each element and its associated IDL interface for now. The
- * rest of the extraction logic is currently disabled because it does not yet
- * produce fully machine-readable results, see inline comments prefixed with
- * "TODO" for details.
- *
- * @function
- * @public
- */
-export default function () {
-  function getText(el) {
-    return el.textContent.trim().replace(/\s+/g, ' ');
-  }
-
-  // Extract HTML elements
-  const htmlElements = [...document.querySelectorAll('dl.element')]
-    .map(el => {
-      // Get back to heading that defines the element(s)
-      let heading = el.previousElementSibling;
-      while (heading && !heading.nodeName.match(/^H\d$/)) {
-        heading = heading.previousElementSibling;
-      }
-      if (!heading) {
-        throw new Error('Could not locate heading associated with element');
-      }
-
-      const dfns = [...heading.querySelectorAll('dfn')];
-      if (dfns.length === 0) {
-        // Ignore the definition of "Custom elements" in HTML
-        if (getText(heading).match(/Core concepts/)) {
-          return null;
-        }
-        throw new Error('No dfn found in heading element: ' + heading.textContent);
-      }
-
-      // In most cases, there will be only one element, but some elements are
-      // defined together, typically h1-h6 or sub and sup
-      return dfns.map(dfn => {
-        const res = { name: getText(dfn) };
-        const dts = [...el.querySelectorAll('dt')];
-        dts.forEach(dt => {
-          const prop = ({
-            // TODO: Properties other than "interface" follow common patterns
-            // most of the time... but not always, making it hard to  create
-            // fully machine-readable info. Uncomment following lines to extract
-            // more info and improve the code
-            // 'Categories': 'categories',
-            // 'Contexts in which this element can be used': 'contexts',
-            // 'Content model': 'contents',
-            // 'Tag omission in text/html': 'omission',
-            // 'Content attributes': 'attributes',
-            // 'Accessibility considerations': 'accessibility',
-            'DOM interface': 'interface'
-          })[getText(dt).replace(/:$/, '')];
-
-          if (prop === 'omission') {
-            // Tag omission can be a complex paragraph but it is never a list.
-            let dd = dt.nextElementSibling;
-            while (dd && dd.nodeName !== 'DD') {
-              dd = dd.nextElementSibling;
-            }
-            if (dd) {
-              res[prop] = getText(dd);
-            }
-          }
-          else if (prop === 'accessibility') {
-            // TODO: Accessibility considerations links to ARIA and AAM. The
-            // code does not yet handle more complex associations that currently
-            // appear in the definitions of the img, sub and sup, input and
-            // select elements.
-            res[prop] = [];
-            let dd = dt.nextElementSibling;
-            while (dd && dd.nodeName !== 'DT') {
-              if (dd.nodeName === 'DD') {
-                const link = dd.querySelector('a');
-                if (link) {
-                  res[prop].push({
-                    title: getText(link),
-                    href: link.getAttribute('href')
-                  });
-                }
-              }
-              dd = dd.nextElementSibling;
-            }
-          }
-          else if (prop === 'interface') {
-            let dd = dt.nextElementSibling;
-            while (dd && dd.nodeName !== 'DD') {
-              dd = dd.nextElementSibling;
-            }
-            if (dd) {
-              let match = dd.textContent.match(/^interface (.*?) /m);
-              if (match) {
-                res[prop] = match[1];
-              }
-              else {
-                // NB: The sub/sup table uses a plural form for "Use", hence
-                // the "?" for the final "s" in "Uses".
-                match = dd.textContent.match(/^Uses? (.*?)[,\.\s]/);
-                if (match) {
-                  res[prop] = match[1];
-                }
-                else {
-                  throw new Error('Could not link element to interface: ' + getText(dd));
-                }
-              }
-            }
-            else {
-              throw new Error('Could not link element to interface, missing dd for ' + res.name);
-            }
-          }
-          else if (prop) {
-            res[prop] = [];
-            let dd = dt.nextElementSibling;
-            while (dd && dd.nodeName !== 'DT') {
-              if (dd.nodeName === 'DD') {
-                res[prop].push(getText(dd).replace(/\.$/, ''));
-              }
-              dd = dd.nextElementSibling;
-            }
-          }
-        });
-        return res;
-      });
-    })
-    .filter(el => !!el)
-    .flat();
-
-
-  // Extract SVG elements that use the "element-summary" pattern
-  const svgSummaryElements = [...document.querySelectorAll('div.element-summary')]
-    .map(el => {
-      const name = el.querySelector('.element-name');
-      if (!name) {
-        throw new Error('Could not extract name from element-summary element');
-      }
-
-      const res = { name: getText(name).replace(/‘|’/g, '') };
-      const dts = [...el.querySelectorAll('dt')];
-      dts.forEach(dt => {
-        const prop = ({
-          'DOM Interfaces': 'interface'
-        })[getText(dt).replace(/:$/, '')];
-        
-        if (prop === 'interface') {
-          let dd = dt.nextElementSibling;
-          while (dd && dd.nodeName !== 'DD') {
-            dd = dd.nextElementSibling;
-          }
-          if (dd) {
-            // For some reason, the "discard" element has no interface:
-            // https://svgwg.org/specs/animations/#DiscardElement
-            if (getText(dd)) {
-              res[prop] = getText(dd);
-            }
-          }
-          else {
-            throw new Error('Could not link element to interface, missing dd for ' + res.name);
-          }
-        }
-      });
-      return res;
-    });
-
-
-  // Extract SVG elements that use the "definition-table" pattern
-  const svgTableElements = [...document.querySelectorAll('table.definition-table')]
-    .map(el => {
-      const dfn = el.querySelector('dfn');
-      if (!dfn) {
-        throw new Error('Could not extract name from definition-table element');
-      }
-
-      const res = { name: getText(dfn) };
-      const ths = [...el.querySelectorAll('th')];
-      ths.forEach(th => {
-        const prop = ({
-          'DOM Interfaces': 'interface'
-        })[getText(th).replace(/:$/, '')];
-        
-        if (prop === 'interface') {
-          let td = th.nextElementSibling;
-          while (td && td.nodeName !== 'TD') {
-            td = td.nextElementSibling;
-          }
-          if (td) {
-            res[prop] = getText(td);
-          }
-          else {
-            throw new Error('Could not link element to interface, missing cell for ' + res.name);
-          }
-        }
-      });
-      return res;
-    });
-
-  return htmlElements.concat(svgSummaryElements, svgTableElements);
-}
+/**
+ * Extract the list of markup elements that the spec defines
+ *
+ * Extraction requires spec to follow a structure similar to the one used in
+ * the HTML spec:
+ * https://html.spec.whatwg.org/multipage/dom.html#element-definitions
+ *
+ * Important (2021-05-31): Extraction code is incomplete and only extracts the
+ * mapping between each element and its associated IDL interface for now. The
+ * rest of the extraction logic is currently disabled because it does not yet
+ * produce fully machine-readable results, see inline comments prefixed with
+ * "TODO" for details.
+ *
+ * @function
+ * @public
+ */
+export default function () {
+  function getText(el) {
+    return el.textContent.trim().replace(/\s+/g, ' ');
+  }
+
+  // Extract HTML elements
+  const htmlElements = [...document.querySelectorAll('dl.element')]
+    .map(el => {
+      // Get back to heading that defines the element(s)
+      let heading = el.previousElementSibling;
+      while (heading && !heading.nodeName.match(/^H\d$/)) {
+        heading = heading.previousElementSibling;
+      }
+      if (!heading) {
+        throw new Error('Could not locate heading associated with element');
+      }
+
+      const dfns = [...heading.querySelectorAll('dfn')];
+      if (dfns.length === 0) {
+        // Ignore the definition of "Custom elements" in HTML
+        if (getText(heading).match(/Core concepts/)) {
+          return null;
+        }
+        throw new Error('No dfn found in heading element: ' + heading.textContent);
+      }
+
+      // In most cases, there will be only one element, but some elements are
+      // defined together, typically h1-h6 or sub and sup
+      return dfns.map(dfn => {
+        const res = { name: getText(dfn) };
+        const dts = [...el.querySelectorAll('dt')];
+        dts.forEach(dt => {
+          const prop = ({
+            // TODO: Properties other than "interface" follow common patterns
+            // most of the time... but not always, making it hard to  create
+            // fully machine-readable info. Uncomment following lines to extract
+            // more info and improve the code
+            // 'Categories': 'categories',
+            // 'Contexts in which this element can be used': 'contexts',
+            // 'Content model': 'contents',
+            // 'Tag omission in text/html': 'omission',
+            // 'Content attributes': 'attributes',
+            // 'Accessibility considerations': 'accessibility',
+            'DOM interface': 'interface'
+          })[getText(dt).replace(/:$/, '')];
+
+          if (prop === 'omission') {
+            // Tag omission can be a complex paragraph but it is never a list.
+            let dd = dt.nextElementSibling;
+            while (dd && dd.nodeName !== 'DD') {
+              dd = dd.nextElementSibling;
+            }
+            if (dd) {
+              res[prop] = getText(dd);
+            }
+          }
+          else if (prop === 'accessibility') {
+            // TODO: Accessibility considerations links to ARIA and AAM. The
+            // code does not yet handle more complex associations that currently
+            // appear in the definitions of the img, sub and sup, input and
+            // select elements.
+            res[prop] = [];
+            let dd = dt.nextElementSibling;
+            while (dd && dd.nodeName !== 'DT') {
+              if (dd.nodeName === 'DD') {
+                const link = dd.querySelector('a');
+                if (link) {
+                  res[prop].push({
+                    title: getText(link),
+                    href: link.getAttribute('href')
+                  });
+                }
+              }
+              dd = dd.nextElementSibling;
+            }
+          }
+          else if (prop === 'interface') {
+            let dd = dt.nextElementSibling;
+            while (dd && dd.nodeName !== 'DD') {
+              dd = dd.nextElementSibling;
+            }
+            if (dd) {
+              let match = dd.textContent.match(/^interface (.*?) /m);
+              if (match) {
+                res[prop] = match[1];
+              }
+              else {
+                // NB: The sub/sup table uses a plural form for "Use", hence
+                // the "?" for the final "s" in "Uses".
+                match = dd.textContent.match(/^Uses? (.*?)[,\.\s]/);
+                if (match) {
+                  res[prop] = match[1];
+                }
+                else {
+                  throw new Error('Could not link element to interface: ' + getText(dd));
+                }
+              }
+            }
+            else {
+              throw new Error('Could not link element to interface, missing dd for ' + res.name);
+            }
+          }
+          else if (prop) {
+            res[prop] = [];
+            let dd = dt.nextElementSibling;
+            while (dd && dd.nodeName !== 'DT') {
+              if (dd.nodeName === 'DD') {
+                res[prop].push(getText(dd).replace(/\.$/, ''));
+              }
+              dd = dd.nextElementSibling;
+            }
+          }
+        });
+        return res;
+      });
+    })
+    .filter(el => !!el)
+    .flat();
+
+
+  // Extract SVG elements that use the "element-summary" pattern
+  const svgSummaryElements = [...document.querySelectorAll('div.element-summary')]
+    .map(el => {
+      const name = el.querySelector('.element-name');
+      if (!name) {
+        throw new Error('Could not extract name from element-summary element');
+      }
+
+      const res = { name: getText(name).replace(/‘|’/g, '') };
+      const dts = [...el.querySelectorAll('dt')];
+      dts.forEach(dt => {
+        const prop = ({
+          'DOM Interfaces': 'interface'
+        })[getText(dt).replace(/:$/, '')];
+        
+        if (prop === 'interface') {
+          let dd = dt.nextElementSibling;
+          while (dd && dd.nodeName !== 'DD') {
+            dd = dd.nextElementSibling;
+          }
+          if (dd) {
+            // For some reason, the "discard" element has no interface:
+            // https://svgwg.org/specs/animations/#DiscardElement
+            if (getText(dd)) {
+              res[prop] = getText(dd);
+            }
+          }
+          else {
+            throw new Error('Could not link element to interface, missing dd for ' + res.name);
+          }
+        }
+      });
+      return res;
+    });
+
+
+  // Extract SVG elements that use the "definition-table" pattern
+  const svgTableElements = [...document.querySelectorAll('table.definition-table')]
+    .map(el => {
+      const dfn = el.querySelector('dfn');
+      if (!dfn) {
+        throw new Error('Could not extract name from definition-table element');
+      }
+
+      const res = { name: getText(dfn) };
+      const ths = [...el.querySelectorAll('th')];
+      ths.forEach(th => {
+        const prop = ({
+          'DOM Interfaces': 'interface'
+        })[getText(th).replace(/:$/, '')];
+        
+        if (prop === 'interface') {
+          let td = th.nextElementSibling;
+          while (td && td.nodeName !== 'TD') {
+            td = td.nextElementSibling;
+          }
+          if (td) {
+            res[prop] = getText(td);
+          }
+          else {
+            throw new Error('Could not link element to interface, missing cell for ' + res.name);
+          }
+        }
+      });
+      return res;
+    });
+
+  return htmlElements.concat(svgSummaryElements, svgTableElements);
+}

package/src/browserlib/extract-headings.mjs

@@ -1,48 +1,48 @@
-import getAbsoluteUrl from './get-absolute-url.mjs';
-
-/**
- * Extract headings data from documents
-*/
-export default function (spec, idToHeading) {
-  // Compute once whether we created a single page version out of multiple pages
-  const singlePage = !document.querySelector('[data-reffy-page]');
-
-  // Headings using the markup convention of the EcmaScript spec
-  const esHeadings = [...document.querySelectorAll('emu-clause[id] > h1')].map(n => {
-    const headingNumber = n.querySelector(".secnum")?.textContent;
-    const headingLevel = headingNumber ? headingNumber.split(".").length : undefined;
-    return {
-      id: n.parentNode.id,
-      title: n.textContent.replace(headingNumber, '').trim(),
-      level: headingLevel,
-      number: headingNumber
-    };
-  });
-  return esHeadings.concat([...document.querySelectorAll('h1[id], h2[id], h3[id], h4[id], h5[id] ,h6[id]')].map(n => {
-    // Note: In theory, all <hX> heading elements that have an ID are associated
-    // with a heading in idToHeading. One exception to the rule: when the
-    // heading element appears in a <hgroup> element, the mapping is not
-    // properly done (the outline creation algorithm explicitly skips these
-    // headings not to create a mess in the outline). In practice, this only
-    // really happens so far for WHATWG spec titles that (correctly) group the
-    // title and subtitle headings in a <hgroup>.
-    const href = getAbsoluteUrl(n, { singlePage });
-    const heading = idToHeading[href] || {
-      id: n.id,
-      href,
-      title: n.textContent.trim()
-    };
-
-    const res = {
-      id: heading.id,
-      href: heading.href,
-      level: parseInt(n.tagName.slice(1), 10),
-      title: heading.title
-    };
-    if (heading.number) {
-      res.number = heading.number;
-    }
-
-    return res;
-  }));
-}
+import getAbsoluteUrl from './get-absolute-url.mjs';
+
+/**
+ * Extract headings data from documents
+*/
+export default function (spec, idToHeading) {
+  // Compute once whether we created a single page version out of multiple pages
+  const singlePage = !document.querySelector('[data-reffy-page]');
+
+  // Headings using the markup convention of the EcmaScript spec
+  const esHeadings = [...document.querySelectorAll('emu-clause[id] > h1')].map(n => {
+    const headingNumber = n.querySelector(".secnum")?.textContent;
+    const headingLevel = headingNumber ? headingNumber.split(".").length : undefined;
+    return {
+      id: n.parentNode.id,
+      title: n.textContent.replace(headingNumber, '').trim(),
+      level: headingLevel,
+      number: headingNumber
+    };
+  });
+  return esHeadings.concat([...document.querySelectorAll('h1[id], h2[id], h3[id], h4[id], h5[id] ,h6[id]')].map(n => {
+    // Note: In theory, all <hX> heading elements that have an ID are associated
+    // with a heading in idToHeading. One exception to the rule: when the
+    // heading element appears in a <hgroup> element, the mapping is not
+    // properly done (the outline creation algorithm explicitly skips these
+    // headings not to create a mess in the outline). In practice, this only
+    // really happens so far for WHATWG spec titles that (correctly) group the
+    // title and subtitle headings in a <hgroup>.
+    const href = getAbsoluteUrl(n, { singlePage });
+    const heading = idToHeading[href] || {
+      id: n.id,
+      href,
+      title: n.textContent.trim()
+    };
+
+    const res = {
+      id: heading.id,
+      href: heading.href,
+      level: parseInt(n.tagName.slice(1), 10),
+      title: heading.title
+    };
+    if (heading.number) {
+      res.number = heading.number;
+    }
+
+    return res;
+  }));
+}

package/src/browserlib/extract-ids.mjs

@@ -1,28 +1,28 @@
-import getAbsoluteUrl from './get-absolute-url.mjs';
-
-/**
- * Extract absolute ids from documents
-*/
-export default function () {
-  // Compute once whether we created a single page version out of multiple pages
-  const singlePage = !document.querySelector('[data-reffy-page]');
-
-  return [...document.querySelectorAll('*[id]')]
-    // Ignore respec- prefixed ids to avoid keeping track of their evolution
-    // They're clearly not meant to be link target in any case
-    .filter(n => !n.id.startsWith('respec-'))
-
-    // Ignore dfn-panel- prefixed ids that ReSpec generates to avoid keeping
-    // track of their evolution. They're clearly not meant to be link target
-    // either.
-    .filter(n => !n.id.startsWith('dfn-panel-'))
-
-    // Convert IDs to absolute URLs (needed to handle multipage specs)
-    .map(n => getAbsoluteUrl(n, { singlePage }))
-
-    // Capture anchors set in <a name> when they're not dup of ids
-    .concat([...document.querySelectorAll('a[name]')]
-      .filter(n => !n.id || n.id !== n.name)
-      .map(n => getAbsoluteUrl(n, { singlePage, attribute: 'name' }))
-    );
-}
+import getAbsoluteUrl from './get-absolute-url.mjs';
+
+/**
+ * Extract absolute ids from documents
+*/
+export default function () {
+  // Compute once whether we created a single page version out of multiple pages
+  const singlePage = !document.querySelector('[data-reffy-page]');
+
+  return [...document.querySelectorAll('*[id]')]
+    // Ignore respec- prefixed ids to avoid keeping track of their evolution
+    // They're clearly not meant to be link target in any case
+    .filter(n => !n.id.startsWith('respec-'))
+
+    // Ignore dfn-panel- prefixed ids that ReSpec generates to avoid keeping
+    // track of their evolution. They're clearly not meant to be link target
+    // either.
+    .filter(n => !n.id.startsWith('dfn-panel-'))
+
+    // Convert IDs to absolute URLs (needed to handle multipage specs)
+    .map(n => getAbsoluteUrl(n, { singlePage }))
+
+    // Capture anchors set in <a name> when they're not dup of ids
+    .concat([...document.querySelectorAll('a[name]')]
+      .filter(n => !n.id || n.id !== n.name)
+      .map(n => getAbsoluteUrl(n, { singlePage, attribute: 'name' }))
+    );
+}

package/src/browserlib/extract-links.mjs

@@ -1,28 +1,28 @@
-import { canonicalizeUrl } from './canonicalize-url.mjs';
-
-/**
- * Extract and canonicalize absolute links of the document and their fragments
- * FIXME: ⚠ Modify the DOM
-*/
-export default function () {
-  // Ignore links from the "head" section, which either link to
-  // self, the GitHub repo, the implementation report, and other
-  // documents that don't need to appear in the list of references.
-  const links = {};
-  [...document.querySelectorAll('.head a[href]')].forEach(n => n.href = '');
-  document.querySelectorAll('a[href^=http]').forEach(n => {
-    const url = canonicalizeUrl(n.href);
-    if (!links[url]) {
-      links[url] = new Set();
-    }
-    if (n.href.includes('#') && n.href.split('#')[1]) {
-      links[url].add(n.href.split('#')[1]);
-    }
-  });
-  return Object.keys(links)
-  // turning sets into arrays
-    .reduce((acc, u) => {
-      acc[u] = [...links[u]];
-      return acc;
-  }, {});
-}
+import { canonicalizeUrl } from './canonicalize-url.mjs';
+
+/**
+ * Extract and canonicalize absolute links of the document and their fragments
+ * FIXME: ⚠ Modify the DOM
+*/
+export default function () {
+  // Ignore links from the "head" section, which either link to
+  // self, the GitHub repo, the implementation report, and other
+  // documents that don't need to appear in the list of references.
+  const links = {};
+  [...document.querySelectorAll('.head a[href]')].forEach(n => n.href = '');
+  document.querySelectorAll('a[href^=http]').forEach(n => {
+    const url = canonicalizeUrl(n.href);
+    if (!links[url]) {
+      links[url] = new Set();
+    }
+    if (n.href.includes('#') && n.href.split('#')[1]) {
+      links[url].add(n.href.split('#')[1]);
+    }
+  });
+  return Object.keys(links)
+  // turning sets into arrays
+    .reduce((acc, u) => {
+      acc[u] = [...links[u]];
+      return acc;
+  }, {});
+}