feat(yasr): Allow plugins to execute background SPARQL queries

[Copilot]

YASR plugins had no way to run additional SPARQL queries at runtime — blocking use cases like graph node expansion (e.g. running DESCRIBE <uri> on click) without replacing the main result display.

Changes

packages/yasr/src/index.ts

• Adds PluginQueryOptions interface ({ acceptHeader?: string })
• Adds executeQuery? callback to Config — decouples execution logic from YASR itself, letting integrators supply it
• Adds public executeQuery(query, options?) on Yasr — delegates to the config callback; rejects with a descriptive error if none is configured

packages/yasgui/src/Tab.ts

• Wires executeQuery in initYasr to Yasqe.Sparql.executeQuery, inheriting the tab's full endpoint/auth/CORS config automatically

docs/developer-guide.md

• Adds "Executing Background Queries from a Plugin" section covering the API, a graph node-expansion example, and standalone YASR usage

Plugin usage

async expandNode(uri: string): Promise<void> {
  const response = await this.yasr.executeQuery(`DESCRIBE <${uri}>`, {
    acceptHeader: 'text/turtle',
  });
  // update visualization with response — main Yasr display is untouched
}

When YASR is used standalone (without YASGUI), supply the callback in config:

const yasr = new Yasr(element, {
  executeQuery: async (query, options) => {
    // your fetch logic
  },
});

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Allow plugins to execute a background query</issue_title>
<issue_description>Needed for: Matdata-eu/yasgui-graph-plugin#10</issue_description>

Comments on the Issue (you are @copilot in this section)

@MathiasVDA We’re building a YASR visualization plugin (Graph plugin) that can expand nodes on click by running a follow-up SPARQL query (e.g., DESCRIBE or a small CONSTRUCT around the clicked resource) in the background and then merging the returned triples into the visualization.

Today, a YASR plugin only has access to the YASR instance and the current results (e.g., yasr.results.getBindings() and yasr.resultsEl). This is enough to render current results, but not enough to reliably execute new SPARQL queries because the plugin cannot access:

• the active tab’s endpoint / requestConfig (headers/auth, method, default graphs, etc.)
• a supported way to run a query through the same execution pipeline YASGUI uses

As a result, plugins would need to duplicate request logic with fetch, which breaks consistency and complicates auth/proxy handling.

Expose something like:

• yasr.executeQuery(query: string, opts?: { requestConfigOverride?: Partial }) => Promise<YasrResultsLike | RawResponse>

The implementation should reuse the same endpoint + requestConfig as the current YASGUI tab (YASQE/YASGUI).

Acceptance criteria

• A YASR plugin can, on user interaction, run a new SPARQL query without hardcoding an endpoint and without duplicating request logic.
• The background query uses the same requestConfig as the active YASGUI tab (endpoint, headers/auth, method, etc.).
• The API is documented as part of the plugin interface (what’s stable, what isn’t).
• cancellation support (abort previous expansion query when user clicks a different node

• Fixes Allow plugins to execute a background query #94

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.