feat(inlines): support [[[SPEC#id]]] for cross-spec section links

src/core/data-cite.js

@@ -184,11 +184,31 @@ export async function run() {
 
   await updateBiblio([...elems]);
 
+  // Capture original keys before toCiteDetails mutates dataset.cite.
+  const originalKeys = new Map();
+  const citeDetailsMap = new Map();
   for (const elem of elems) {
-    const originalKey = elem.dataset.cite;
-    const citeDetails = toCiteDetails(elem);
+    originalKeys.set(elem, elem.dataset.cite);
+    citeDetailsMap.set(elem, toCiteDetails(elem));
+  }
+
+  for (const elem of elems) {
+    const originalKey = originalKeys.get(elem);
+    const citeDetails = citeDetailsMap.get(elem);
     const linkProps = await getLinkProps(citeDetails);
     if (linkProps) {
+      // Use alias text (data-lt) if present and element is empty.
+      // Only applies to [[[...]]] triple-bracket expansions (which set data-lt for
+      // alias text). IDL references also use data-lt as a lookup term but already
+      // have child content, so the textContent check prevents corrupting them.
+      if (
+        elem.dataset.lt &&
+        elem.dataset.lt !== "the-empty-string" &&
+        elem.textContent === ""
+      ) {
+        elem.textContent = elem.dataset.lt;
+        delete elem.dataset.lt;
+      }
       linkElem(elem, linkProps, citeDetails);
     } else {
       const msg = `Couldn't find a match for "${originalKey}"`;

src/core/inlines.js

@@ -69,7 +69,8 @@ const inlineCodeRegExp = /(?:`[^`]+`)(?!`)/; // `code`
 const inlineIdlReference = /(?:{{[^}]+\?*}})/; // {{ WebIDLThing }}, {{ WebIDLThing? }}
 const inlineVariable = /\B\|\w[\w\s]*(?:\s*:[\w\s&;"?<>]+\??)?\|\B/; // |var : Type?|
 const inlineCitation = /(?:\[\[(?:!|\\|\?)?[\w.-]+(?:|[^\]]+)?\]\])/; // [[citation]]
-const inlineExpansion = /(?:\[\[\[(?:!|\\|\?)?#?[\w-.]+\]\]\])/; // [[[expand]]]
+const inlineExpansion =
+  /(?:\[\[\[(?:!|\\|\?)?(?:#[\w-.]+|[\w-.]+(?:#[\w-.]+)?)(?:\|[^\]]+)?\]\]\])/; // [[[expand]]], [[[#id]]], [[[#id|text]]], [[[SPEC]]], [[[SPEC|text]]], [[[SPEC#id]]], or [[[SPEC#id|text]]]
 const inlineAnchor = /(?:\[=[^=]+=\])/; // Inline [= For/link =]
 const inlineElement = /(?:\[\^[^^]+\^\])/; // Inline [^element^]
 
@@ -128,11 +129,21 @@ function inlineRFC2119Matches(matched) {
  */
 function inlineRefMatches(matched) {
   // slices "[[[" at the beginning and "]]]" at the end
-  const ref = matched.slice(3, -3).trim();
+  let ref = matched.slice(3, -3).trim();
+  const pipeIdx = ref.indexOf("|");
+  const linkText = pipeIdx !== -1 ? ref.slice(pipeIdx + 1).trim() : null;
+  if (pipeIdx !== -1) ref = ref.slice(0, pipeIdx).trim();
+
   if (!ref.startsWith("#")) {
-    return html`<a data-cite="${ref}" data-matched-text="${matched}"></a>`;
+    return html`<a
+      data-cite="${ref}"
+      data-matched-text="${matched}"
+      data-lt="${linkText || null}"
+    ></a>`;
   }
-  return html`<a href="${ref}" data-matched-text="${matched}"></a>`;
+  return linkText
+    ? html`<a href="${ref}" data-matched-text="${matched}">${linkText}</a>`
+    : html`<a href="${ref}" data-matched-text="${matched}"></a>`;
 }
 
 /**

tests/spec/core/inlines-spec.js

@@ -284,6 +284,194 @@
     expect(notFound.textContent).toBe("[[[not-found]]]");
   });
 
+  it("classifies [[[!SPEC#id]]] as normative and [[[?SPEC#id]]] as informative", async () => {
+    const config = {
+      localBiblio: {
+        "the-spec": {
+          id: "the-spec",
+          title: "The Spec",
+          href: "https://example.com/",
+        },
+        "other-spec": {
+          id: "other-spec",
+          title: "Other Spec",
+          href: "https://example.com/other",
+        },
+      },
+    };
+    const body = `
+      <section id="test">
+        <section class="informative">
+          <p id="norm-frag">[[[!the-spec#some-id]]]</p>
+        </section>
+        <section id="conformance">
+          <p id="inform-frag">[[[?other-spec#some-id]]]</p>
+        </section>
+      </section>
+    `;
+    const doc = await makeRSDoc(makeStandardOps(config, body));
+
+    // [[[!the-spec#some-id]]] forces normative even in informative section
+    const normAnchor = doc.querySelector("#norm-frag a");
+    expect(normAnchor).toBeTruthy();
+    expect(normAnchor.textContent).toBe("The Spec");
+
+    const norm = [...doc.querySelectorAll("#normative-references dt")];
+    expect(norm.map(el => el.textContent)).toContain("[the-spec]");
+
+    // [[[?other-spec#some-id]]] forces informative even in normative section
+    const informAnchor = doc.querySelector("#inform-frag a");
+    expect(informAnchor).toBeTruthy();
+    expect(informAnchor.textContent).toBe("Other Spec");
+
+    const inform = [...doc.querySelectorAll("#informative-references dt")];
+    expect(inform.map(el => el.textContent)).toContain("[other-spec]");
+  });
+
+  it("supports [[[?SPEC#id|alias]]] and [[[?SPEC|alias]]] with informative classification", async () => {
+    const config = {
+      localBiblio: {
+        "the-spec": {
+          id: "the-spec",
+          title: "The Spec",
+          href: "https://example.com/",
+        },
+        "other-spec": {
+          id: "other-spec",
+          title: "Other Spec",
+          href: "https://example.com/other",
+        },
+      },
+    };
+    const body = `
+      <section id="test">
+        <section id="conformance">
+          <p id="inform-alias">[[[?the-spec#some-id|custom link text]]]</p>
+          <p id="inform-no-frag">[[[?other-spec|just the spec]]]</p>
+        </section>
+      </section>
+    `;
+    const doc = await makeRSDoc(makeStandardOps(config, body));
+
+    // Alias text should be used instead of spec title
+    const aliasAnchor = doc.querySelector("#inform-alias a");
+    expect(aliasAnchor).toBeTruthy();
+    expect(aliasAnchor.textContent).toBe("custom link text");
+
+    const noFragAnchor = doc.querySelector("#inform-no-frag a");
+    expect(noFragAnchor).toBeTruthy();
+    expect(noFragAnchor.textContent).toBe("just the spec");
+
+    // Both should be classified as informative
+    const inform = [...doc.querySelectorAll("#informative-references dt")];
+    expect(inform.map(el => el.textContent)).toContain("[the-spec]");
+    expect(inform.map(el => el.textContent)).toContain("[other-spec]");
+  });
+
+  it("shows matched text as fallback for [[[not-found|Custom Text]]]", async () => {
+    const body = `
+      <section id="test" class="informative">
+        <p id="output">[[[not-found|Custom Text]]]</p>
+      </section>
+    `;
+    const doc = await makeRSDoc(makeStandardOps({}, body));
+    const output = doc.querySelector("#output");
+    expect(output).toBeTruthy();
+    // When the spec is not found, the original matched text is shown
+    expect(output.textContent.trim()).toBe("[[[not-found|Custom Text]]]");
+  });
+
+  it("links to specific section of another spec using [[[SPEC#id]]] syntax", async () => {
+    const config = {
+      localBiblio: {
+        fetch: {
+          title: "Fetch Standard",
+          href: "https://fetch.spec.whatwg.org/",
+        },
+      },
+    };
+    const body = `
+      <section id="test">
+        <p id="output">[[[fetch#data-fetch]]]</p>
+      </section>
+    `;
+    const doc = await makeRSDoc(makeStandardOps(config, body));
+    const anchor = doc.querySelector("#output a[href]");
+    expect(anchor).toBeTruthy();
+    expect(anchor.href).toBe("https://fetch.spec.whatwg.org/#data-fetch");
+    expect(anchor.textContent).toBe("Fetch Standard");
+  });
+
+  it("supports alias text with [[[SPEC#id|text]]] syntax", async () => {
+    const config = {
+      localBiblio: {
+        fetch: {
+          title: "Fetch Standard",
+          href: "https://fetch.spec.whatwg.org/",
+        },
+      },
+    };
+    const body = `
+      <section id="test">
+        <p id="alias">[[[fetch#data-fetch|fetching data]]]</p>
+        <p id="no-alias">[[[fetch#data-fetch]]]</p>
+      </section>
+    `;
+    const doc = await makeRSDoc(makeStandardOps(config, body));
+    const aliasAnchor = doc.querySelector("#alias a[href]");
+    expect(aliasAnchor).toBeTruthy();
+    expect(aliasAnchor.href).toBe("https://fetch.spec.whatwg.org/#data-fetch");
+    expect(aliasAnchor.textContent).toBe("fetching data");
+
+    const noAliasAnchor = doc.querySelector("#no-alias a[href]");
+    expect(noAliasAnchor).toBeTruthy();
+    // spec title is used as link text when no alias is provided
+    expect(noAliasAnchor.textContent).toBe("Fetch Standard");
+  });
+
+  it("supports alias text with [[[SPEC|text]]] syntax (no fragment)", async () => {
+    const config = {
+      localBiblio: {
+        fetch: {
+          title: "Fetch Standard",
+          href: "https://fetch.spec.whatwg.org/",
+        },
+      },
+    };
+    const body = `
+      <section id="test">
+        <p id="alias">[[[fetch|Custom Fetch Link]]]</p>
+        <p id="no-alias">[[[fetch]]]</p>
+      </section>
+    `;
+    const doc = await makeRSDoc(makeStandardOps(config, body));
+    const aliasAnchor = doc.querySelector("#alias a[href]");
+    expect(aliasAnchor).toBeTruthy();
+    expect(aliasAnchor.href).toBe("https://fetch.spec.whatwg.org/");
+    expect(aliasAnchor.textContent).toBe("Custom Fetch Link");
+
+    const noAliasAnchor = doc.querySelector("#no-alias a[href]");
+    expect(noAliasAnchor).toBeTruthy();
+    expect(noAliasAnchor.textContent).toBe("Fetch Standard");
+  });
+
+  it("supports alias text with [[[#id|text]]] for in-document links", async () => {
+    const body = `
+      <section id="my-section">
+        <h2>My Section Heading</h2>
+        <p>Some content.</p>
+      </section>
+      <section>
+        <h2>References</h2>
+        <p id="output">[[[#my-section|see this section]]]</p>
+      </section>
+    `;
+    const doc = await makeRSDoc(makeStandardOps(null, body));
+    const anchor = doc.querySelector("#output a[href='#my-section']");
+    expect(anchor).toBeTruthy();
+    expect(anchor.textContent).toBe("see this section");
+  });
+
   it("allows [[[#...]]] to be a general expander for ids in document", async () => {
     /** @param {string} text */
     function generateDataIncludeUrl(text) {
@@ -329,6 +517,17 @@
     expect(badOne.textContent).toBe("#does-not-exist");
   });
 
+  it("does not process [[[#id#invalid]]] with multiple hash fragments", async () => {
+    const body = `
+      <section id="section"><h2>Section</h2></section>
+      <p id="output">[[[#section#invalid]]]</p>
+    `;
+    const doc = await makeRSDoc(makeStandardOps(null, body));
+    const output = doc.getElementById("output");
+    expect(output.querySelector("a")).toBeNull();
+    expect(output.textContent.trim()).toBe("[[[#section#invalid]]]");
+  });
+
   it("proceseses backticks inside [= =] inline links", async () => {
     const body = `
       <section>