fix(core/dfn): treat internal slots as IDL attributes

src/core/dfn.js

@@ -2,8 +2,16 @@
 // Module core/dfn
 // - Finds all <dfn> elements and populates definitionMap to identify them.
 
-import { getDfnTitles, norm } from "./utils.js";
+import {
+  codedJoinOr,
+  docLink,
+  getDfnTitles,
+  norm,
+  showError,
+  toMDCode,
+} from "./utils.js";
 import { registerDefinition } from "./dfn-map.js";
+import { slotRegex } from "./inline-idl-parser.js";
 
 export const name = "core/dfn";
 
@@ -12,9 +20,10 @@ export function run() {
     const titles = getDfnTitles(dfn);
     registerDefinition(dfn, titles);
 
-    // Treat Internal Slots as IDL.
-    if (!dfn.dataset.dfnType && /^\[\[\w+\]\]$/.test(titles[0])) {
-      dfn.dataset.dfnType = "idl";
+    const [linkingText] = titles;
+    // Matches attributes and methods, like [[some words]](with, optional, arguments)
+    if (slotRegex.test(linkingText)) {
+      processAsInternalSlot(linkingText, dfn);
     }
 
     // Per https://tabatkins.github.io/bikeshed/#dfn-export, a dfn with dfnType
@@ -26,9 +35,52 @@ export function run() {
     }
 
     // Only add `lt`s that are different from the text content
-    if (titles.length === 1 && titles[0] === norm(dfn.textContent)) {
+    if (titles.length === 1 && linkingText === norm(dfn.textContent)) {
       return;
     }
     dfn.dataset.lt = titles.join("|");
   });
 }
+/**
+ *
+ * @param {string} title
+ * @param {HTMLElement} dfn
+ */
+function processAsInternalSlot(title, dfn) {
+  if (!dfn.dataset.hasOwnProperty("idl")) {
+    dfn.dataset.idl = "";
+  }
+
+  // Automatically use the closest data-dfn-for as the parent.
+  /** @type HTMLElement */
+  const parent = dfn.closest("[data-dfn-for]");
+  if (dfn !== parent && parent?.dataset.dfnFor) {
+    dfn.dataset.dfnFor = parent.dataset.dfnFor;
+  }
+
+  // Assure that it's data-dfn-for= something.
+  if (!dfn.dataset.dfnFor) {
+    const msg = `Internal slot "${title}" must be associated with a WebIDL interface.`;
+    const hint = docLink`Use a ${"[data-dfn-for]"} attribute to associate this dfn with a WebIDL interface.`;
+    showError(msg, name, { hint, elements: [dfn] });
+  }
+
+  // If it ends with a ), then it's method. Attribute otherwise.
+  const derivedType = title.endsWith(")") ? "method" : "attribute";
+  if (!dfn.dataset.dfnType) {
+    dfn.dataset.dfnType = derivedType;
+    return;
+  }
+
+  // Perform validation on the dfn's type.
+  const allowedSlotTypes = ["attribute", "method"];
+  const { dfnType } = dfn.dataset;
+  if (!allowedSlotTypes.includes(dfnType) || derivedType !== dfnType) {
+    const msg = docLink`Invalid ${"[data-dfn-type]"} attribute on internal slot.`;
+    const prettyTypes = codedJoinOr(allowedSlotTypes, {
+      quotes: true,
+    });
+    const hint = `The only allowed types are: ${prettyTypes}. The slot "${title}" seems to be a "${toMDCode(derivedType)}"?`;
+    showError(msg, name, { hint, elements: [dfn] });
+  }
+}

src/core/inline-idl-parser.js

@@ -7,16 +7,18 @@ import { html } from "./import-maps.js";
 const idlPrimitiveRegex = /^[a-z]+(\s+[a-z]+)+\??$/; // {{unrestricted double?}} {{ double }}
 const exceptionRegex = /\B"([^"]*)"\B/; // {{ "SomeException" }}
 const methodRegex = /(\w+)\((.*)\)$/;
-const slotRegex = /^\[\[(\w+)\]\]$/;
+
+export const slotRegex = /^\[\[(\w+(?: +\w+)*)\]\](\([^)]*\))?$/;
 // matches: `value` or `[[value]]`
 // NOTE: [[value]] is actually a slot, but database has this as type="attribute"
-const attributeRegex = /^((?:\[\[)?(?:\w+)(?:\]\])?)$/;
+const attributeRegex = /^((?:\[\[)?(?:\w+(?: +\w+)*)(?:\]\])?)$/;
 const baseRegex = /^(?:\w+)\??$/;
 const enumRegex = /^(\w+)\["([\w- ]*)"\]$/;
 // TODO: const splitRegex = /(?<=\]\]|\b)\./
 // https://github.com/w3c/respec/pull/1848/files#r225087385
 const methodSplitRegex = /\.?(\w+\(.*\)$)/;
-
+const slotSplitRegex = /\.?\/(.+)/;
+const isProbablySlotRegex = /^\[\[.+\]\]/;
 /**
  * @typedef {object} IdlBase
  * @property {"base"} type
@@ -34,8 +36,10 @@ const methodSplitRegex = /\.?(\w+\(.*\)$)/;
  * @typedef {object} IdlInternalSlot
  * @property {"internal-slot"} type
  * @property {string} identifier
+ * @property {string[]} [args]
  * @property {boolean} renderParent
  * @property {InlineIdl | null} [parent]
+ * @property {"attribute"|"method"} slotType
  *
  * @typedef {object} IdlMethod
  * @property {"method"} type
@@ -71,7 +75,11 @@ const methodSplitRegex = /\.?(\w+\(.*\)$)/;
  * @returns {InlineIdl[]}
  */
 function parseInlineIDL(str) {
-  const [nonMethodPart, methodPart] = str.split(methodSplitRegex);
+  // If it's got [[ string ]], then split as an internal slot
+  const splitter = isProbablySlotRegex.test(str)
+    ? slotSplitRegex
+    : methodSplitRegex;
+  const [nonMethodPart, methodPart] = str.split(splitter);
   const tokens = nonMethodPart
     .split(/[./]/)
     .concat(methodPart)
@@ -108,8 +116,19 @@ function parseInlineIDL(str) {
     }
     // internal slot
     if (slotRegex.test(value)) {
-      const [, identifier] = value.match(slotRegex);
-      results.push({ type: "internal-slot", identifier, renderParent });
+      const [, identifier, allArgs] = value.match(slotRegex);
+      const slotType = allArgs ? "method" : "attribute";
+      const args = allArgs
+        ?.slice(1, -1)
+        .split(/,\s*/)
+        .filter(arg => arg);
+      results.push({
+        type: "internal-slot",
+        slotType,
+        identifier,
+        args,
+        renderParent,
+      });
       continue;
     }
     // attribute
@@ -167,15 +186,20 @@ function renderBase(details) {
  * @param {IdlInternalSlot} details
  */
 function renderInternalSlot(details) {
-  const { identifier, parent, renderParent } = details;
+  const { identifier, parent, slotType, renderParent, args } = details;
   const { identifier: linkFor } = parent || {};
-  const lt = `[[${identifier}]]`;
+  const isMethod = slotType === "method";
+  const argsHtml = isMethod
+    ? htmlJoinComma(args, arg => html`<var>${arg}</var>`)
+    : null;
+  const textArgs = isMethod ? `(${args.join(", ")})` : "";
+  const lt = `[[${identifier}]]${textArgs}`;
   const element = html`${parent && renderParent ? "." : ""}<a
-      data-xref-type="attribute"
-      data-link-for=${linkFor}
-      data-xref-for=${linkFor}
+      data-xref-type="${slotType}"
+      data-link-for="${linkFor}"
+      data-xref-for="${linkFor}"
       data-lt="${lt}"
-      ><code>[[${identifier}]]</code></a
+      ><code>[[${identifier}]]${isMethod ? html`(${argsHtml})` : null}</code></a
     >`;
   return element;
 }

tests/spec/core/dfn-spec.js

@@ -153,4 +153,75 @@ describe("Core — Definitions", () => {
       expect(el.hash).toBe("#dfn-first");
     }
   });
+
+  describe("internal slot definitions", () => {
+    const body = `
+      <section data-dfn-for="Test" data-cite="HTML">
+        <h2>Internal slots</h2>
+        <pre class="idl">
+          [Exposed=Window]
+          interface Foo{};
+        </pre>
+        <p>
+          <dfn id="attribute">
+            [[\\internal slot]]
+          </dfn>
+          <dfn id="method">
+            [[\\I am_a method]](I, really, ...am)
+          </dfn>
+          <dfn id="parent" data-dfn-for="Window">[[\\internal slot]]</dfn>
+          <dfn id="broken" data-dfn-for="">[[\\broken]]</dfn>
+        </p>
+        <section data-dfn-for="">
+          <h2>.</h2>
+          <p>
+            <dfn id="broken-parent">[[\\broken]]</dfn>
+          </p>
+        </section>
+        <p>
+        {{Test/[[internal slot]]}}
+        {{Test/[[I am_a method]](I, really, ...am)}}
+        {{Window/[[internal slot]]}}
+        </p>
+      </section>
+    `;
+
+    it("sets the data-dfn-type as an attribute", async () => {
+      const ops = makeStandardOps(null, body);
+      const doc = await makeRSDoc(ops);
+      const dfn = doc.getElementById("attribute");
+      expect(dfn.textContent.trim()).toBe("[[internal slot]]");
+      expect(dfn.dataset.dfnType).toBe("attribute");
+      expect(dfn.dataset.idl).toBe("");
+    });
+
+    it("sets the data-dfn-type as a method, when it's a method", async () => {
+      const ops = makeStandardOps(null, body);
+      const doc = await makeRSDoc(ops);
+      const dfn = doc.getElementById("method");
+      expect(dfn.textContent.trim()).toBe(
+        "[[I am_a method]](I, really, ...am)"
+      );
+      expect(dfn.dataset.dfnType).toBe("method");
+      expect(dfn.dataset.idl).toBe("");
+    });
+
+    it("when data-dfn-for is missing, it use the closes data-dfn-for as parent", async () => {
+      const ops = makeStandardOps(null, body);
+      const doc = await makeRSDoc(ops);
+      const dfn = doc.getElementById("attribute");
+      expect(dfn.dataset.dfnFor).toBe("Test");
+      const dfnWithParent = doc.getElementById("parent");
+      expect(dfnWithParent.dataset.dfnFor).toBe("Window");
+    });
+
+    it("errors if the internal slot is not for something", async () => {
+      const ops = makeStandardOps(null, body);
+      const doc = await makeRSDoc(ops);
+      const dfnErrors = doc.respec.errors.filter(
+        ({ plugin }) => plugin === "core/dfn"
+      );
+      expect(dfnErrors).toHaveSize(2);
+    });
+  });
 });

tests/spec/core/link-to-dfn-spec.js

@@ -9,7 +9,9 @@ describe("Core — Link to definitions", () => {
     const bodyText = `
       <section>
         <h2>Test section</h2>
-        <p><dfn>[[\\test]]</dfn><a id="testAnchor">[[\\test]]</a>
+        <p>
+          <dfn data-dfn-for="Window">[[\\test]]</dfn>
+          <a data-link-for="Window" id="testAnchor">[[\\test]]</a>
       </section>`;
     const ops = makeStandardOps(null, bodyText);
     const doc = await makeRSDoc(ops);
@@ -139,10 +141,12 @@ describe("Core — Link to definitions", () => {
     const body = `
       <section id="test">
         <dfn data-dfn-for="MyEvent">[[\\aSlot]]</dfn>
+        <dfn data-dfn-for="MyEvent">[[\\an internal slot]](foo, bar)</dfn>
         <dfn>MyEvent</dfn>
         <p id="link-slots">
           <span>{{ MyEvent/[[aSlot]] }}</span>
           <span>{{ MyEvent.[[aSlot]] }}</span>
+          <span>{{ MyEvent/[[an internal slot]](foo, bar) }}</span>
         </p>
       </section>
     `;
@@ -156,6 +160,53 @@ describe("Core — Link to definitions", () => {
     expect(links[1].hash).toBe(href);
   });
 
+  it("supports internal slot being a method with no args", async () => {
+    const body = `
+      <section>
+        <dfn id="method" data-dfn-for="MyEvent">
+          [[\\an internal_slot]]()
+        </dfn>
+        <dfn>MyEvent</dfn>
+        <p id="link-slots">
+          <span>{{ MyEvent/[[an internal_slot]]() }}</span>
+        </p>
+      </section>
+    `;
+    const ops = makeStandardOps(null, body);
+    const doc = await makeRSDoc(ops);
+
+    const dfn = doc.querySelector("#method");
+    const links = doc.querySelectorAll("#link-slots a");
+    expect(links[0].hash).toBe(`#${dfn.id}`);
+    const vars = document.querySelectorAll("#link-slots var");
+    expect(vars).toHaveSize(0);
+  });
+
+  it("supports internal slot being a method with arguments", async () => {
+    const body = `
+      <section>
+        <dfn id="method" data-dfn-for="MyEvent">
+          [[\\an internal_slot]](foo, bar)
+        </dfn>
+        <dfn>MyEvent</dfn>
+        <p id="link-slots">
+          <span>{{ MyEvent/[[an internal_slot]](foo, bar) }}</span>
+        </p>
+      </section>
+    `;
+    const ops = makeStandardOps(null, body);
+    const doc = await makeRSDoc(ops);
+
+    const dfn = doc.querySelector("#method");
+    const links = doc.querySelectorAll("#link-slots a");
+    expect(links[0].hash).toBe(`#${dfn.id}`);
+    const vars = doc.querySelectorAll("#link-slots var");
+    expect(vars).toHaveSize(2);
+    const [foo, bar] = vars;
+    expect(foo.textContent).toBe("foo");
+    expect(bar.textContent).toBe("bar");
+  });
+
   it("has empty data-dfn-for on top level things", async () => {
     const bodyText = `
       <section data-dfn-for="HyperStar" data-link-for="HyperStar">

tests/spec/core/simple.html

@@ -30,7 +30,6 @@ <h2>Some title</h2>
     Some content
   </p>
   <p><dfn id="custom_id(¡™£¢∞§¶•ªº)">custom id</dfn></p>
-  <p><dfn>[[\escapedSlot]]</dfn> <a>[[\escapedSlot]]</a></p>
 </section>
 <section data-dfn-for="Test">
   <h2><dfn>Test</dfn> interface</h2>
@@ -42,5 +41,9 @@ <h2><dfn>Test</dfn> interface</h2>
   </pre>
   <section>
     <h3><dfn>foo()</dfn> method</h3>
+    <p>
+      <dfn>[[\escapedSlot]]</dfn>
+      {{Test/[[escapedSlot]]}}
+    </p>
   </section>
 </section>

tests/spec/core/xref-spec.js

@@ -756,9 +756,12 @@ describe("Core — xref", () => {
     it("links internalSlots", async () => {
       const body = `
       <section>
-        <p><dfn>[[\\type]]</dfn></p>
-        <p id="link1">{{ [[type]] }}</p>
+        <p><dfn data-dfn-for="Window">[[\\type]]</dfn></p>
+        <p id="link1">{{ Window/[[type]] }}</p>
         <p id="link2">{{ Credential.[[type]] }}</p>
+        <p id="link3">{{
+          PasswordCredential/[[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors)
+        }}</p>
       </section>
       `;
       const config = { xref: true, localBiblio };
@@ -780,6 +783,13 @@ describe("Core — xref", () => {
       );
       expect(link2a.firstElementChild.localName).toBe("code");
       expect(link2b.firstElementChild.localName).toBe("code");
+
+      // [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors)
+      const link3 = doc.querySelector("#link3 a");
+      expect(link3.firstElementChild.localName).toBe("code");
+      expect(link3.href).toBe(
+        "https://www.w3.org/TR/credential-management-1/#dom-passwordcredential-collectfromcredentialstore-slot"
+      );
     });
 
     it("links enum and enum-values", async () => {