mdn · escattone · Aug 16, 2021 · Jun 4, 2021 · Jun 9, 2021 · Jun 9, 2021
@@ -31,6 +31,7 @@ const { gather: gatherGitHistory } = require("./git-history");
 const { buildSPAs } = require("./spas");
 const { renderCache: renderKumascriptCache } = require("../kumascript");
 const LANGUAGES_RAW = require("../content/languages.json");
+const { safeDecodeURIComponent } = require("../kumascript/src/api/util");
 
 const LANGUAGES = new Map(
   Object.entries(LANGUAGES_RAW).map(([locale, data]) => {
@@ -298,8 +299,8 @@ async function buildDocument(document, documentOptions = {}) {
 
   doc.flaws = {};
 
-  let renderedHtml = "";
   let flaws = [];
+  let renderedHtml = "";
   const liveSamples = [];
 
   if (options.clearKumascriptRenderCache) {
@@ -319,26 +320,21 @@ async function buildDocument(document, documentOptions = {}) {
         `MacroInvocationError trying to parse ${error.filepath}, line ${error.line} column ${error.column} (${error.error.message})`
       );
     }
-
     // Any other unexpected error re-thrown.
     throw error;
   }
 
-  const sampleIds = kumascript.getLiveSampleIDs(
-    document.metadata.slug,
+  const $ = cheerio.load(`<div id="_body">${renderedHtml}</div>`);
+
+  const liveSamplePages = kumascript.buildLiveSamplePages(
+    document.url,
+    document.metadata.title,
+    $,
     document.rawBody
   );
-  for (const sampleIdObject of sampleIds) {
-    const liveSamplePage = kumascript.buildLiveSamplePage(
-      document.url,
-      document.metadata.title,
-      renderedHtml,
-      sampleIdObject
-    );
-
-    let liveSampleHTML = liveSamplePage.html;
-    if (liveSamplePage.flaw) {
-      const flaw = liveSamplePage.flaw.updateFileInfo(fileInfo);
+  for (let { id, html, flaw } of liveSamplePages) {
+    if (flaw) {
+      flaw.updateFileInfo(fileInfo);
       if (flaw.name === "MacroLiveSampleError") {
         // As of April 2021 there are 0 pages in mdn/content that trigger
         // a MacroLiveSampleError. So we can be a lot more strict with en-US
@@ -356,7 +352,7 @@ async function buildDocument(document, documentOptions = {}) {
         }
       }
       flaws.push(flaw);
-      liveSampleHTML = `<!doctype html>
+      html = `<!doctype html>
         <html>
           <head>
             <meta charset="utf-8">
@@ -382,10 +378,7 @@ async function buildDocument(document, documentOptions = {}) {
         </html>
         `;
     }
-    liveSamples.push({
-      id: sampleIdObject.id.toLowerCase(),
-      html: liveSampleHTML,
-    });
+    liveSamples.push({ id: id.toLowerCase(), html });
   }
 
   if (flaws.length) {
@@ -438,7 +431,9 @@ async function buildDocument(document, documentOptions = {}) {
   // its output with the `folder`.
   validateSlug(metadata.slug);
 
-  const $ = cheerio.load(`<div id="_body">${renderedHtml}</div>`);
+  // EmbedLiveSamples carry their token information to enrich flaw error
+  // messages, these should not be in the final output
+  $("[data-token]").removeAttr("data-token");
 
   // Kumascript rendering can't know about FLAW_LEVELS when it's building,
   // because injecting it there would cause a circular dependency.
@@ -620,30 +615,30 @@ async function buildLiveSamplePageFromURL(url) {
     throw new Error(`Unexpected URL format to extract live sample ('${url}')`);
   }
   const [documentURL, sampleID] = url.split(/\.html$/)[0].split("/_sample_.");
+  const decodedSampleID = safeDecodeURIComponent(sampleID).toLowerCase();
   const document = Document.findByURL(documentURL);
   if (!document) {
     throw new Error(`No document found for ${documentURL}`);
   }
-  // Convert the lower-case sampleID we extract from the incoming URL into
-  // the actual sampleID object with the properly-cased live-sample ID.
-  for (const sampleIDObject of kumascript.getLiveSampleIDs(
-    document.metadata.slug,
-    document.rawBody
-  )) {
-    if (sampleIDObject.id.toLowerCase() === sampleID) {
-      const liveSamplePage = kumascript.buildLiveSamplePage(
-        document.url,
-        document.metadata.title,
-        (await kumascript.render(document.url))[0],
-        sampleIDObject
-      );
-      if (liveSamplePage.flaw) {
-        throw new Error(liveSamplePage.flaw.toString());
-      }
-      return liveSamplePage.html;
+  const liveSamplePage = kumascript
+    .buildLiveSamplePages(
+      document.url,
+      document.metadata.title,
+      (await kumascript.render(document.url))[0],
+      document.rawBody
+    )
+    .find((page) => page.id.toLowerCase() == decodedSampleID);
+
+  if (liveSamplePage) {
+    if (liveSamplePage.flaw) {
+      throw new Error(liveSamplePage.flaw.toString());
     }
+    return liveSamplePage.html;
   }
-  throw new Error(`No live-sample "${sampleID}" found within ${documentURL}`);
+
+  throw new Error(
+    `No live-sample "${decodedSampleID}" found within ${documentURL}`
+  );
 }
 
 // This is used by the builder (yarn build) and by the server (JIT).

@@ -71,6 +71,7 @@ export function Document(props /* TODO: define a TS interface for this */) {
           ? props.doc
           : null,
       revalidateOnFocus: CRUD_MODE,
+      refreshInterval: CRUD_MODE ? 500 : 0,
     }
   );
 

@@ -11,7 +11,7 @@ const info = require("./src/info.js");
 const { render: renderMacros } = require("./src/render.js");
 const {
   getLiveSampleIDs,
-  buildLiveSamplePage,
+  buildLiveSamplePages,
   LiveSampleError,
 } = require("./src/live-sample.js");
 const { HTMLTool } = require("./src/api/util.js");
@@ -114,7 +114,7 @@ const renderFromURL = async (
 };
 
 module.exports = {
-  buildLiveSamplePage,
+  buildLiveSamplePages,
   getLiveSampleIDs,
   LiveSampleError,
   render: renderFromURL,

@@ -14,7 +14,7 @@
 //
 // See also : LiveSampleLink
 
-var sampleId = $0;
+var sampleId = $0 || $token.location.start.offset;
 var width = $1;
 var height = $2;
 var screenshotUrl = $3;
@@ -80,5 +80,6 @@ if (width) { %> width="<%= width %>"<% }
 if (height) { %> height="<%= height %>"<% }
 %> src="<%- url %>"<%
 if (allowedFeatures) { %> allow="<%= allowedFeatures %>"<% }
+if ($token) { %> data-token="<%= JSON.stringify($token) %>"<% }
 %>></iframe><%
 if (hasScreenshot) { %></td></tr></tbody></table><% } %>
@@ -67,9 +67,68 @@ function safeDecodeURIComponent(text) {
   }
 }
 
+const findSectionStart = ($, sectionID) =>
+  $(`#${cssesc(sectionID, { isIdentifier: true })}`);
+
+const hasHeading = ($, sampleID) =>
+  !sampleID ? false : findSectionStart($, sampleID).length > 0;
+
+function findTopLevelParent($el) {
+  while ($el.siblings(":header").length == 0 && $el.parent().length > 0) {
+    $el = $el.parent();
+  }
+  return $el;
+}
+
+const getLevel = ($header) => parseInt($header[0].name[1], 10);
+
+const getHigherHeaderSelectors = (upTo) =>
+  Array.from({ length: upTo }, (_, i) => "h" + (i + 1)).join(", ");
+
+function* collectLevels($el) {
+  // Initialized to 7 so that we pick up the lowest heading level which is <h6>
+  let level = 7;
+  let $prev = $el;
+  while (level !== 1) {
+    const nextHigherLevel = getHigherHeaderSelectors(level - 1);
+    const $header = $prev.prevAll(nextHigherLevel).first();
+    if ($header.length == 0) {
+      return;
+    }
+    level = getLevel($header);
+    $prev = $header;
+    yield $header.add($header.nextUntil(nextHigherLevel));
+  }
+}
+
+function collectClosestCode($start) {
+  const $el = findTopLevelParent($start);
+  for (const $level of collectLevels($el)) {
+    const pairs = LIVE_SAMPLE_PARTS.map((part) => {
+      const selector = `.${part}, pre[class*="brush:${part}"], pre[class*="${part};"]`;
+      const $filtered = $level.find(selector).add($level.filter(selector));
+      return [
+        part,
+        $filtered
+          .map((i, element) => cheerio(element).text())
+          .get()
+          .join("\n"),
+      ];
+    });
+    if (pairs.some(([, code]) => !!code)) {
+      $start.prop("title", $level.first(":header").text());
+      return Object.fromEntries(pairs);
+    }
+  }
+  return null;
+}
+
 class HTMLTool {
   constructor(html, pathDescription) {
-    this.$ = cheerio.load(html, { decodeEntities: true });
+    this.$ =
+      typeof html == "string"
+        ? cheerio.load(html, { decodeEntities: true })
+        : html;
     this.pathDescription = pathDescription;
   }
 
@@ -139,7 +198,7 @@ class HTMLTool {
     // Kuma looks for the first HTML tag of a limited set of section tags with ANY
     // attribute equal to the "sectionID", but in practice it's always an "id" attribute,
     // so let's simplify this as well as make it much faster.
-    const sectionStart = $(`#${cssesc(sectionID, { isIdentifier: true })}`);
+    const sectionStart = findSectionStart($, sectionID);
     if (!sectionStart.length) {
       let errorMessage = `unable to find an HTML element with an "id" of "${sectionID}" within ${this.pathDescription}`;
       const hasMoreThanAscii = [...sectionID].some(
@@ -182,33 +241,44 @@ class HTMLTool {
   }
 
   extractLiveSampleObject(sampleID) {
-    const result = Object.create(null);
-    const sample = this.getSection(sampleID);
-    // We have to wrap the collection of elements from the section
-    // we've just acquired because we're going to search among all
-    // descendants and we want to include the elements themselves
-    // as well as their descendants.
-    const $ = cheerio.load(`<div>${cheerio.html(sample)}</div>`);
-    for (const part of LIVE_SAMPLE_PARTS) {
-      const src = $(
-        `.${part},pre[class*="brush:${part}"],pre[class*="${part};"]`
-      )
-        .map((i, element) => {
-          return $(element).text();
-        })
-        .get()
-        .join("\n");
-      // The string replacements below have been carried forward from Kuma:
-      //   * Bugzilla 819999: &nbsp; gets decoded to \xa0, which trips up CSS.
-      //   * Bugzilla 1284781: &nbsp; is incorrectly parsed on embed sample.
-      result[part] = src ? src.replace(/\u00a0/g, " ") : null;
-    }
-    if (!LIVE_SAMPLE_PARTS.some((part) => result[part])) {
-      throw new KumascriptError(
-        `unable to find any live code samples for "${sampleID}" within ${this.pathDescription}`
+    const sectionID = sampleID.substr("frame_".length);
+    if (hasHeading(this.$, sectionID)) {
+      const result = Object.create(null);
+      const sample = this.getSection(sectionID);
+      // We have to wrap the collection of elements from the section
+      // we've just acquired because we're going to search among all
+      // descendants and we want to include the elements themselves
+      // as well as their descendants.
+      const $ = cheerio.load(`<div>${cheerio.html(sample)}</div>`);
+      for (const part of LIVE_SAMPLE_PARTS) {
+        const src = $(
+          `.${part}, pre[class*="brush:${part}"], pre[class*="${part};"]`
+        )
+          .map((i, element) => $(element).text())
+          .get()
+          .join("\n");
+        // The string replacements below have been carried forward from Kuma:
+        //   * Bugzilla 819999: &nbsp; gets decoded to \xa0, which trips up CSS.
+        //   * Bugzilla 1284781: &nbsp; is incorrectly parsed on embed sample.
+        result[part] = src ? src.replace(/\u00a0/g, " ") : null;
+      }
+      if (!LIVE_SAMPLE_PARTS.some((part) => result[part])) {
+        throw new KumascriptError(
+          `unable to find any live code samples for "${sectionID}" within ${this.pathDescription}`
+        );
+      }
+      return result;
+    } else {
+      const result = collectClosestCode(
+        this.$("#" + cssesc(sampleID, { isIdentifier: true }))
       );
+      if (!result) {
+        throw new KumascriptError(
+          `unable to find any live code samples for "${sectionID}" within ${this.pathDescription}`
+        );
+      }
+      return result;
     }
-    return result;
   }
 
   html() {

@@ -159,7 +159,7 @@ class Environment {
 
   // Get a customized environment object that is specific to a single
   // macro on a page by including the arguments to be passed to that macro.
-  getExecutionContext(args) {
+  getExecutionContext(args, token = null) {
     const context = Object.create(this.prototypeEnvironment);
 
     // Make a defensive copy of the arguments so that macros can't
@@ -188,6 +188,10 @@ class Environment {
       context[`$${i}`] = "";
     }
 
+    // Position of the macro inside of the source, which we need
+    // to identify EmbedLiveSample macros which do not receive an ID
+    context["$token"] = token;
+
     return context;
   }
 }