webidl.js

// Module core/webidl
//  Highlights and links WebIDL marked up inside <pre class="idl">.

// TODO:
//  - It could be useful to report parsed IDL items as events
//  - don't use generated content in the CSS!
import {
  addHashId,
  showInlineError,
  showInlineWarning,
  xmlEscape,
} from "./utils.js";
import { decorateDfn, findDfn } from "./dfn-finder.js";
import { html, webidl2 } from "./import-maps.js";
import { addCopyIDLButton } from "./webidl-clipboard.js";
import { fetchAsset } from "./text-loader.js";
import { registerDefinition } from "./dfn-map.js";

export const name = "core/webidl";

const operationNames = {};
const idlPartials = {};

const templates = {
  wrap(items) {
    return items
      .flat()
      .filter(x => x !== "")
      .map(x => (typeof x === "string" ? new Text(x) : x));
  },
  trivia(t) {
    if (!t.trim()) {
      return t;
    }
    return html`<span class="idlSectionComment">${t}</span>`;
  },
  generic(keyword) {
    // Shepherd classifies "interfaces" as starting with capital letters,
    // like Promise, FrozenArray, etc.
    return /^[A-Z]/.test(keyword)
      ? html`<a data-xref-type="interface" data-cite="WebIDL">${keyword}</a>`
      : // Other keywords like sequence, maplike, etc...
        html`<a data-xref-type="dfn" data-cite="WebIDL">${keyword}</a>`;
  },
  reference(wrapped, unescaped, context) {
    if (context.type === "extended-attribute" && context.name !== "Exposed") {
      return wrapped;
    }
    let type = "_IDL_";
    let cite = null;
    let lt;
    switch (unescaped) {
      case "Window":
        type = "interface";
        cite = "HTML";
        break;
      case "object":
        type = "interface";
        cite = "WebIDL";
        break;
      default: {
        const isWorkerType = unescaped.includes("Worker");
        if (isWorkerType && context.type === "extended-attribute") {
          lt = `${unescaped}GlobalScope`;
          type = "interface";
          cite = ["Worker", "DedicatedWorker", "SharedWorker"].includes(
            unescaped
          )
            ? "HTML"
            : null;
        }
      }
    }
    return html`<a data-xref-type="${type}" data-cite="${cite}" data-lt="${lt}"
      >${wrapped}</a
    >`;
  },
  name(escaped, { data, parent }) {
    if (data.idlType && data.idlType.type === "argument-type") {
      return html`<span class="idlParamName">${escaped}</span>`;
    }
    const idlLink = defineIdlName(escaped, data, parent);
    if (data.type !== "enum-value") {
      const className = parent ? "idlName" : "idlID";
      idlLink.classList.add(className);
    }
    return idlLink;
  },
  nameless(escaped, { data, parent }) {
    switch (data.type) {
      case "constructor":
        return defineIdlName(escaped, data, parent);
      default:
        return escaped;
    }
  },
  type(contents) {
    return html`<span class="idlType">${contents}</span>`;
  },
  inheritance(contents) {
    return html`<span class="idlSuperclass">${contents}</span>`;
  },
  definition(contents, { data, parent }) {
    const className = getIdlDefinitionClassName(data);
    switch (data.type) {
      case "includes":
      case "enum-value":
        return html`<span class="${className}">${contents}</span>`;
    }
    const parentName = parent ? parent.name : "";
    const { name, idlId } = getNameAndId(data, parentName);
    return html`<span
      class="${className}"
      id="${idlId}"
      data-idl
      data-title="${name}"
      >${contents}</span
    >`;
  },
  extendedAttribute(contents) {
    const result = html`<span class="extAttr">${contents}</span>`;
    return result;
  },
  extendedAttributeReference(name) {
    return html`<a data-xref-type="extended-attribute">${name}</a>`;
  },
};

/**
 * Returns a link to existing <dfn> or creates one if doesn’t exists.
 */
function defineIdlName(escaped, data, parent) {
  const parentName = parent ? parent.name : "";
  const { name } = getNameAndId(data, parentName);
  const dfn = findDfn(data, name, {
    parent: parentName,
  });
  const linkType = getDfnType(data.type);
  if (dfn) {
    if (!data.partial) {
      dfn.dataset.export = "";
      dfn.dataset.dfnType = linkType;
    }
    decorateDfn(dfn, data, parentName, name);
    const href = `#${dfn.id}`;
    return html`<a
      data-link-for="${parentName}"
      data-link-type="${linkType}"
      href="${href}"
      class="internalDFN"
      ><code>${escaped}</code></a
    >`;
  }

  const isDefaultJSON =
    data.type === "operation" &&
    data.name === "toJSON" &&
    data.extAttrs.some(({ name }) => name === "Default");
  if (isDefaultJSON) {
    return html`<a data-link-type="dfn" data-lt="default toJSON steps"
      >${escaped}</a
    >`;
  }
  if (!data.partial) {
    const dfn = html`<dfn data-export data-dfn-type="${linkType}"
      >${escaped}</dfn
    >`;
    registerDefinition(dfn, [name]);
    decorateDfn(dfn, data, parentName, name);
    return dfn;
  }

  const unlinkedAnchor = html`<a
    data-idl="${data.partial ? "partial" : null}"
    data-link-type="${linkType}"
    data-title="${data.name}"
    data-xref-type="${linkType}"
    >${escaped}</a
  >`;

  const showWarnings =
    name && data.type !== "typedef" && !(data.partial && !dfn);
  if (showWarnings) {
    const styledName = data.type === "operation" ? `${name}()` : name;
    const ofParent = parentName ? ` \`${parentName}\`'s` : "";
    const msg = `Missing \`<dfn>\` for${ofParent} \`${styledName}\` ${data.type}. [More info](https://github.com/w3c/respec/wiki/WebIDL-thing-is-not-defined).`;
    showInlineWarning(unlinkedAnchor, msg, "");
  }
  return unlinkedAnchor;
}

/**
 * Map to Shepherd types, for export.
 * @see https://tabatkins.github.io/bikeshed/#dfn-types
 */
function getDfnType(idlType) {
  switch (idlType) {
    case "operation":
      return "method";
    case "field":
      return "dict-member";
    case "callback interface":
    case "interface mixin":
      return "interface";
    default:
      return idlType;
  }
}

function getIdlDefinitionClassName(defn) {
  switch (defn.type) {
    case "callback interface":
      return "idlInterface";
    case "operation":
      return "idlMethod";
    case "field":
      return "idlMember";
    case "enum-value":
      return "idlEnumItem";
    case "callback function":
      return "idlCallback";
  }
  return `idl${defn.type[0].toUpperCase()}${defn.type.slice(1)}`;
}

const nameResolverMap = new WeakMap();
function getNameAndId(defn, parent = "") {
  if (nameResolverMap.has(defn)) {
    return nameResolverMap.get(defn);
  }
  const result = resolveNameAndId(defn, parent);
  nameResolverMap.set(defn, result);
  return result;
}

function resolveNameAndId(defn, parent) {
  let name = getDefnName(defn);
  let idlId = getIdlId(name, parent);
  switch (defn.type) {
    // Top-level entities with linkable members.
    case "callback interface":
    case "dictionary":
    case "interface":
    case "interface mixin": {
      idlId += resolvePartial(defn);
      break;
    }
    case "constructor":
    case "operation": {
      const overload = resolveOverload(name, parent);
      if (overload) {
        name += overload;
        idlId += overload;
      } else if (defn.arguments.length) {
        idlId += defn.arguments
          .map(arg => `-${arg.name.toLowerCase()}`)
          .join("");
      }
      break;
    }
  }
  return { name, idlId };
}

function resolvePartial(defn) {
  if (!defn.partial) {
    return "";
  }
  if (!idlPartials[defn.name]) {
    idlPartials[defn.name] = 0;
  }
  idlPartials[defn.name] += 1;
  return `-partial-${idlPartials[defn.name]}`;
}

function resolveOverload(name, parentName) {
  const qualifiedName = `${parentName}.${name}`;
  const fullyQualifiedName = `${qualifiedName}()`;
  let overload;
  if (!operationNames[fullyQualifiedName]) {
    operationNames[fullyQualifiedName] = 0;
  }
  if (!operationNames[qualifiedName]) {
    operationNames[qualifiedName] = 0;
  } else {
    overload = `!overload-${operationNames[qualifiedName]}`;
  }
  operationNames[fullyQualifiedName] += 1;
  operationNames[qualifiedName] += 1;
  return overload || "";
}

function getIdlId(name, parentName) {
  if (!parentName) {
    return `idl-def-${name.toLowerCase()}`;
  }
  return `idl-def-${parentName.toLowerCase()}-${name.toLowerCase()}`;
}

function getDefnName(defn) {
  switch (defn.type) {
    case "enum-value":
      return defn.value;
    case "operation":
      return defn.name;
    default:
      return defn.name || defn.type;
  }
}

/**
 * @param {Element} idlElement
 * @param {number} index
 */
function renderWebIDL(idlElement, index) {
  let parse;
  try {
    parse = webidl2.parse(idlElement.textContent, {
      sourceName: String(index),
    });
  } catch (e) {
    showInlineError(
      idlElement,
      `Failed to parse WebIDL: ${e.bareMessage}.`,
      e.bareMessage,
      { details: `<pre>${e.context}</pre>` }
    );
    // Skip this <pre> and move on to the next one.
    return [];
  }
  addDataDfnFor(idlElement, parse);
  // we add "idl" as the canonical match, so both "webidl" and "idl" work
  idlElement.classList.add("def", "idl");
  const highlights = webidl2.write(parse, { templates });
  html.bind(idlElement)`${highlights}`;
  idlElement.querySelectorAll("[data-idl]").forEach(elem => {
    if (elem.dataset.dfnFor) {
      return;
    }
    const title = elem.dataset.title;
    // Select the nearest ancestor element that can contain members.
    const parent = elem.parentElement.closest("[data-idl][data-title]");
    if (parent) {
      elem.dataset.dfnFor = parent.dataset.title;
    }
    if (elem.localName === "dfn") {
      registerDefinition(elem, [title]);
    }
  });
  // cross reference
  const closestCite = idlElement.closest("[data-cite], body");
  const { dataset } = closestCite;
  if (!dataset.cite) dataset.cite = "WebIDL";
  // includes webidl in some form
  if (!/\bwebidl\b/i.test(dataset.cite)) {
    const cites = dataset.cite.trim().split(/\s+/);
    dataset.cite = ["WebIDL", ...cites].join(" ");
  }
  addIDLHeader(idlElement);
  return parse;
}

/**
 * Add data-dfn-for to the closest section if not present already.
 * @param {HTMLPreElement} idlElement
 * @param {ReturnType<typeof webidl2.parse>} parse
 */
function addDataDfnFor(idlElement, parse) {
  const closestSection = idlElement.closest("section");
  if (closestSection.hasAttribute("data-dfn-for")) return;

  const topLevelEntities = ["dictionary", "interface", "callback interface"];

  const dfnFors = [];
  for (const { tokens } of parse) {
    if (topLevelEntities.includes(tokens.base.type)) {
      const dfnFor = tokens.name.value;
      dfnFors.push(dfnFor);
    }
  }
  if (dfnFors.length === 1) {
    closestSection.dataset.dfnFor = dfnFors[0];
  } else if (!dfnFors.length) {
    return;
  } else {
    closestSection.dataset.dfnFor = "";
    const options = dfnFors.map(dfnFor => `"${dfnFor}"`).join(", ");
    const title = "Ambiguous data-dfn-for attribute";
    const message = `${title}. Sections describing top-level IDL entities (${topLevelEntities}) require a \`data-dfn-attribute\`. Please add a \`data-dfn-for\` attribute with one of following values: ${options}`;
    showInlineError(closestSection, message, title);
  }
}

/**
 * Adds a "WebIDL" decorative header/permalink to a block of WebIDL.
 * @param {HTMLPreElement} pre
 */
export function addIDLHeader(pre) {
  addHashId(pre, "webidl");
  const header = html`<span class="idlHeader"
    ><a class="self-link" href="${`#${pre.id}`}">WebIDL</a></span
  >`;
  pre.prepend(header);
  addCopyIDLButton(header);
}

const cssPromise = loadStyle();

async function loadStyle() {
  try {
    return (await import("text!../../assets/webidl.css")).default;
  } catch {
    return fetchAsset("webidl.css");
  }
}

export async function run() {
  const idls = document.querySelectorAll("pre.idl, pre.webidl");
  if (!idls.length) {
    return;
  }
  if (!document.querySelector(".idl:not(pre), .webidl:not(pre)")) {
    const link = document.querySelector("head link");
    if (link) {
      const style = document.createElement("style");
      style.textContent = await cssPromise;
      link.before(style);
    }
  }

  const astArray = [...idls].map(renderWebIDL);

  const validations = webidl2.validate(astArray);
  for (const validation of validations) {
    let details = `<pre>${validation.context}</pre>`;
    if (validation.autofix) {
      validation.autofix();
      const idlToFix = webidl2.write(astArray[validation.sourceName]);
      const escaped = xmlEscape(idlToFix);
      details += `Try fixing as:
      <pre>${escaped}</pre>`;
    }
    showInlineError(
      idls[validation.sourceName],
      `WebIDL validation error: ${validation.bareMessage}`,
      validation.bareMessage,
      { details }
    );
  }
  document.normalize();
}