feat(core/dfn-panel): show linking terms in panel by marcoscaceres · Pull Request #5251 · speced/respec

marcoscaceres · 2026-05-04T01:18:32Z

Screenshot:

Written with AI: this change was generated by Claude. Per AI_POLICY.md.

Copilot

Pull request overview

Adds visibility into a definition’s alternate “linking terms” (from data-lt) by rendering them in the DFN panel, addressing the usability request in #3741.

Changes:

Render a “Linking terms:” line in the DFN panel when data-lt is present and contains aliases beyond the DFN’s own text.
Normalize/dedupe data-lt values for display and omit the term matching the DFN’s text content.
Add a spec test covering presence/absence and whitespace normalization behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
`src/core/dfn-panel.js`	Adds `linkingTermsToHTML()` and injects linking-term display into the panel markup.
`tests/spec/core/dfn-panel-spec.js`	Adds coverage ensuring linking terms appear only when appropriate and handle trimming/deduping.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

marcoscaceres

I'm pretty happy with where this ended up.

sidvishnoi · 2026-11-06T08:39:28Z

+    if ((dfnType === "element-attr" || dfnType === "attr-value") && dfnFor) {
+      return `[^${dfnFor}/${term}^]`;
+    }


If we've dfnFor with other case (element), that should be a warning then? Do we need to special case it here?

Fair question. I tried [^blink^] and [^html/blink^] for an element definition with a data-dfn-for, and neither links. The panel now lists nothing for an element with a for, and the special case is gone. A warning for authors belongs in the definition code, not in this pull request.

sidvishnoi · 2026-11-06T08:59:49Z

+    const btn =
+      target instanceof HTMLElement && target.closest(".dfn-panel-copy-btn");
+    if (!(btn instanceof HTMLElement)) return;
+    const text = btn.dataset.copyText;


Should we grab the textContent (of previous sibling) instead of duplicating text to button?

Done. The button no longer carries data-copy-text, and the runtime copies the text of the code element before the button. The doc comment on createSyntaxCopyButton says the button has to follow the code element.

sidvishnoi · 2026-11-06T09:01:15Z

+  setupCopyButtons();
+}
+
+function setupCopyButtons() {


How about using core/clipboard.js? It has a SVG icon for copy as well.

The copy icon now comes from core/clipboard.js, which exports COPY_SVG. I did not reuse createCopyButton. That function builds the code-block button: 40 by 28 pixels, absolutely positioned, tied to a header selector. The exporter also strips that button from exported specs. The panel's buttons must stay in exported specs and copy a string. The runtime keeps its own click handler, because the handler ships inside the exported page.

sidvishnoi · 2026-11-09T12:25:20Z

-      )}
-    </ul>`;
+  ></button>`;
+  button.innerHTML = COPY_SVG;


Optimization: Add the COPY_SVG once to page as a <symbol>; then reuse it with <use>, so we don't bloat generated HTML. Was less important before with few code blocks, now there's manifold increase.

Done. The page now holds one <symbol> in a hidden SVG, and every button points at the symbol with <use>. The sprite appears only when some panel lists syntaxes. On my test page of 93 definitions, the exported file went from 175,475 bytes (an SVG in every button) to 143,307 bytes.

sidvishnoi · 2026-11-09T12:38:52Z

+    aria-label="Copy ${text} to clipboard"
+    title="Copy to clipboard"


Some screen readers will announce both aria-label and title when they differ. Either make them same, or remove title (safer).

Removed both title and aria-label. The button name now comes from the text inside the button: "Copy" plus the syntax.

sidvishnoi · 2026-11-09T12:39:45Z


-const COPY_SVG =
+export const COPY_SVG =
  '<svg height="16" viewBox="0 0 14 16" width="14"><path fill-rule="evenodd" d="M2 13h4v1H2v-1zm5-6H2v1h5V7zm2 3V8l-3 3 3 3v-2h5v-2H9zM4.5 9H2v1h2.5V9zM2 12h2.5v-1H2v1zm9 1h1v2c-.02.28-.11.52-.3.7-.19.18-.42.28-.7.3H1c-.55 0-1-.45-1-1V4c0-.55.45-1 1-1h3c0-1.11.89-2 2-2 1.11 0 2 .89 2 2h3c.55 0 1 .45 1 1v5h-1V6H1v9h10v-2zM2 5h8c0-.55-.45-1-1-1H8c-.55 0-1-.45-1-1s-.45-1-1-1-1 .45-1 1-.45 1-1 1H3c-.55 0-1 .45-1 1z"/></svg>';


Please mark this SVG as aria-hidden, otherwise it can show like: button [copy to clipboard] > image

Added aria-hidden="true" to COPY_SVG, so the code-block buttons get the attribute too. The icons in the panel have the attribute as well.

sidvishnoi · 2026-11-09T12:42:13Z

+    if (!btn) return;
+    const text = btn.previousElementSibling?.textContent;
+    if (!text) return;
+    navigator.clipboard?.writeText(text).catch(() => {});


Let's add btn.ariaNotify("Copied") as well. Ideally, we should update icon, but let's do this as well.

Added. After a successful copy, the button calls ariaNotify("Copied"). Browsers without ariaNotify skip the call, and a failed copy announces nothing. Chrome has the method. I did not check Safari or Firefox.

sidvishnoi · 2026-11-09T12:46:58Z

+          html`<li>
+            <code>${syntax}</code> ${createSyntaxCopyButton(syntax)}
+          </li>`


Have you considered this markup?

<li> <button type="button"> <span class="visually-hidden">Copy </span><code>${term}</code> <svg aria-hidden="true" …></svg> </button> </li>

I took the markup from your comment. Each row is now one button holding the hidden "Copy ", the code and the icon. The runtime copies the text of the code inside the clicked button. ReSpec had no visually-hidden class, so I added one scoped to the panel. In Chrome, keyboard focus shows the browser's focus ring around the whole row.

Adds a "Possible linking syntaxes:" section to each dfn popup panel, showing the correct ReSpec inline shorthand for linking to the definition. Handles all dfn types: [= =] for concepts, {{ }} for IDL, [^ ^] for elements/attributes, {^ ^} for CDDL. Includes data-lt aliases and per-item copy-to-clipboard buttons. Fixes selectors in dfn-index-spec.js. Closes #3741

Agent-Logs-Url: https://github.com/marcoscaceres/respec/sessions/6ba7d17c-3dc1-4a3a-b086-6c08033f748f

- Add "interface mixin" and "callback interface" to IDL_TYPES - Add removeOnSave to copy buttons so they're stripped from exports - Include buttons in trapFocus selector (a11y: keyboard users can reach copy buttons)

…fault Split comma-separated data-dfn-for values so each produces a separate linking syntax (e.g. {{Foo/method()}} and {{Bar/method()}} instead of the invalid {{Foo, Bar/method()}}). Also skip primaryTerm when data-lt-noDefault is set, matching getDfnTitles behavior.

… link

…initions

marcoscaceres · 2026-11-10T04:32:15Z

I've decided we should only show the linking syntaxes if the definition is exported. Otherwise it might be confusing.

marcoscaceres requested a review from Copilot May 4, 2026 01:20

Copilot started reviewing on behalf of marcoscaceres May 4, 2026 01:21

View session

Copilot AI reviewed May 4, 2026

View reviewed changes

marcoscaceres marked this pull request as ready for review May 4, 2026 11:08

marcoscaceres force-pushed the feat/3741-dfn-panel-lt branch from 13771de to 6cf689e Compare May 10, 2026 09:30

marcoscaceres added the AI Contains AI-generated logic; see AI_POLICY.md label Aug 5, 2026

sidvishnoi self-requested a review November 6, 2026 03:36

marcoscaceres commented Nov 6, 2026

View reviewed changes

sidvishnoi reviewed Nov 6, 2026

View reviewed changes

sidvishnoi reviewed Nov 9, 2026

View reviewed changes

marcoscaceres and others added 11 commits November 10, 2026 00:07

fix(core/dfn-panel): keep copy buttons keyboard-accessible

27e6e55

Agent-Logs-Url: https://github.com/marcoscaceres/respec/sessions/6ba7d17c-3dc1-4a3a-b086-6c08033f748f

fix(core/dfn-panel): add missing IDL types, fix focus trap and export

2bd9cc7

- Add "interface mixin" and "callback interface" to IDL_TYPES - Add removeOnSave to copy buttons so they're stripped from exports - Include buttons in trapFocus selector (a11y: keyboard users can reach copy buttons)

fix(core/dfn-panel): put references first and list only syntaxes that…

5b471a5

… link

test(core/dfn-panel): check copy button rules, not computed style

7aca452

fix(core/dfn-panel): keep copy buttons in exported documents

99b29fe

fix(core/dfn-panel): set copy button type and add a pressed look

51a355a

test(core/dfn-panel): check a copy button does not submit an author form

9457239

test(core/dfn-panel): check Enter on a copy button keeps the panel open

e75ec32

fix(core/dfn-panel): address review feedback

fbc61bb

marcoscaceres force-pushed the feat/3741-dfn-panel-lt branch from 828a81c to fbc61bb Compare November 10, 2026 01:27

fix(core/dfn-panel): one button per syntax row, only for exported def…

32d5ae4

…initions

		aria-label="Copy ${text} to clipboard"
		title="Copy to clipboard"

Conversation

marcoscaceres commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

marcoscaceres left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marcoscaceres commented Nov 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

marcoscaceres commented May 4, 2026 •

edited

Loading

marcoscaceres commented Nov 10, 2026 •

edited

Loading