(Auto)EmbedLiveSample

build/index.js

@@ -299,19 +299,20 @@ async function buildDocument(document, documentOptions = {}) {
 
   doc.flaws = {};
 
-  let renderedHtml = "";
-  let flaws = [];
+  let $;
   const liveSamples = [];
 
   if (doc.isArchive) {
     if (document.isMarkdown) {
       throw new Error("Markdown not supported for archived content");
     }
-    renderedHtml = document.rawBody;
+    $ = cheerio.load(`<div id="_body">${document.rawBody}</div>`);
   } else {
     if (options.clearKumascriptRenderCache) {
       renderKumascriptCache.reset();
     }
+    let renderedHtml;
+    let flaws;
     try {
       [renderedHtml, flaws] = await kumascript.render(document.url);
     } catch (error) {
@@ -331,19 +332,17 @@ async function buildDocument(document, documentOptions = {}) {
       throw error;
     }
 
-    const sampleIds = kumascript.getLiveSampleIDs(
-      document.metadata.slug,
+    $ = 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
-      );
-      if (liveSamplePage.flaw) {
-        const flaw = liveSamplePage.flaw.updateFileInfo(fileInfo);
+    for (const { 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
@@ -361,12 +360,9 @@ async function buildDocument(document, documentOptions = {}) {
           }
         }
         flaws.push(flaw);
-        continue;
+      } else {
+        liveSamples.push({ id: id.toLowerCase(), html });
       }
-      liveSamples.push({
-        id: sampleIdObject.id.toLowerCase(),
-        html: liveSamplePage.html,
-      });
     }
 
     if (flaws.length) {
@@ -420,7 +416,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.
@@ -610,25 +608,22 @@ async function buildLiveSamplePageFromURL(url) {
   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() == sampleID);
+
+  if (liveSamplePage) {
+    if (liveSamplePage.flaw) {
+      throw new Error(liveSamplePage.flaw.toString());
     }
+    return liveSamplePage.html;
   }
+
   throw new Error(`No live-sample "${sampleID}" found within ${documentURL}`);
 }
 

client/src/document/index.tsx

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

kumascript/index.js

@@ -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,

kumascript/macros/EmbedLiveSample.ejs

@@ -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;
@@ -79,5 +79,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><% } %>

kumascript/src/api/util.js

@@ -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 "${sampleID}" 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 "${sampleID}" within ${this.pathDescription}`
+        );
+      }
+      return result;
     }
-    return result;
   }
 
   html() {

kumascript/src/environment.js

@@ -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;
   }
 }