Migrate to monaco editor

.changeset/config.json

@@ -2,7 +2,7 @@
   "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
   "changelog": "@changesets/cli/changelog",
   "commit": false,
-  "fixed": [["@zazuko/*"]],
+  "fixed": [["@rdfjs/*"]],
   "linked": [],
   "access": "public",
   "baseBranch": "main",

.changeset/migrate-to-monaco.md

@@ -0,0 +1,42 @@
+---
+"@rdfjs/sparql-studio": major
+"@rdfjs/sparql-utils": major
+"@rdfjs/sparql-editor-monaco": major
+"@rdfjs/sparql-editor-codemirror": major
+"@rdfjs/sparql-results": major
+---
+
+- Migrate from CodeMirror 5 to Monaco/CodeMirror 6 editors with language servers
+  - Users can now choose between 2 editors: one based on Monaco, the other based on CodeMirror 6
+  - The editor now extends `EventEmitter` instead of `CodeMirror`, with a shared `IEditor` interface both editors implement
+  - Enable use of language servers for diagnostics, syntax highlighting, autocompletion, code actions, hover and formatting
+  - Delete the editor's built-in autocomplete and grammar code (now handled by the language server)
+  - CodeMirror falls back to static SPARQL syntax highlighting when the language server provides no semantic tokens
+  - Update some of the puppeteer tests
+- Language servers
+  - Unified, editor-agnostic language server interface for both Monaco and CodeMirror: you pass a `Worker` (instance or factory) and the editor connects the client for you, waiting for the worker's `ready` signal
+  - Support multiple language servers via a `languageServers` array, with runtime switching (right-click menu in Monaco, dropdown in CodeMirror) and a per-endpoint preference persisted to localStorage
+  - Generic settings panel generated from a JSON schema, with a callback to apply settings to the active server
+  - Improved display of error messages coming from the language server
+  - Ship qlue-ls plumbing (settings, types, backend/endpoint registration, prefix discovery, completion-query templates) in utils under the `qlueLs` namespace, so consumers can wire it up easily
+  - The demo implements 3 language servers: **qlue-ls** (WASM, endpoint-powered completions), **swls** (WASM, semantic web language server) and **Traqula** (JS SPARQL 1.2 parser, diagnostics only)
+- App and editor improvements
+  - Enable light/dark theme
+  - Add a "Share query URL" entry to the Monaco right-click menu (under Execute query) bound to Cmd/Ctrl+S
+  - Update the CodeMirror used by the results viewer to display the raw response JSON from v5 to v6
+  - Update the default SPARQL endpoint from DBpedia to https://sparql.dblp.org/sparql (faster for completion queries)
+  - Improve the partial config implementation (`DeepPartial`)
+  - Enable importing the main JS and CSS from `@rdfjs/sparql-studio` and `@rdfjs/sparql-studio/style.css`
+- Docs
+  - Add a documentation website built with VitePress (served from https://sparql.studio), with an auto-generated API reference (TypeDoc)
+  - The home page is the full app with the 3 language servers, a second page demos the CodeMirror editor
+- Drop UMD support: the libraries are now ESM-only (Monaco loads its workers/wasm via `import.meta.url`, which UMD cannot express). ESM imports work in plain HTML `<script type="module">` in every browsers.
+- Rename the packages and exported classes:
+  - `@zazuko/yasgui` -> `@rdfjs/sparql-studio` (class `Yasgui` -> `SparqlStudio`)
+  - `@zazuko/yasqe` -> `@rdfjs/sparql-editor-monaco` and a new `@rdfjs/sparql-editor-codemirror` (class `Yasqe` -> `SparqlEditor`)
+  - `@zazuko/yasr` -> `@rdfjs/sparql-results` (class `Yasr` -> `SparqlResults`)
+  - `@zazuko/yasgui-utils` -> `@rdfjs/sparql-utils`
+  - The `SparqlStudio` config keys `yasqe`/`yasr` are now `editor`/`results`
+  - Rename `window.yasgui` & cie to `window.sparqlStudio`
+  - Rename CSS classes (`.yasgui* -> `.sparqlStudio*`)
+- add `postcss-nested` to flatten nested CSS

.changeset/migrate-to-vite.md

@@ -1,8 +1,8 @@
 ---
-"@zazuko/yasgui": patch
-"@zazuko/yasgui-utils": patch
-"@zazuko/yasqe": patch
-"@zazuko/yasr": patch
+"@rdfjs/sparql-studio": patch
+"@rdfjs/sparql-utils": patch
+"@rdfjs/sparql-editor-monaco": patch
+"@rdfjs/sparql-results": patch
 ---
 
 - Migrate from `webpack` to `vite` for the bundler and dev server

.github/workflows/test.yaml

@@ -1,17 +1,19 @@
 name: Run tests
 
-on: push
+on:
+  push:
+  workflow_dispatch:
 
 jobs:
   tests:
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6.0.3
 
       - name: Set up NodeJS
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v6.4.0
         with:
           node-version: "lts/*"
           cache: npm
@@ -27,3 +29,50 @@ jobs:
 
       - name: Run tests
         run: npm run test
+
+  docs:
+    name: Deploy to GitHub Pages
+    needs: tests
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    # Allow only one concurrent deployment, skip runs queued between the in-progress and latest.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.3
+
+      - name: Set up NodeJS
+        uses: actions/setup-node@v6.4.0
+        with:
+          node-version: "lts/*"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build libraries
+        run: npm run build:lib
+
+      - name: Build docs
+        run: npm run docs:build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v6.0.0
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5.0.0
+        with:
+          path: docs/.vitepress/dist
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5.0.0

.gitignore

@@ -1,3 +1,7 @@
 node_modules
 build
 yarn.lock
+cache/
+dist/
+# Generated by TypeDoc
+docs/api/

CONTRIBUTING.md

@@ -57,6 +57,10 @@ Using Changesets allows for precise control over releases and supports versionin
 - [Changesets GitHub repository](https://github.com/changesets/changesets)
 - [Common Questions about Changesets](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
 
+### Upgrade dependencies
+
+Checkout [`monaco-languageclient` version compatiblity table](https://github.com/TypeFox/monaco-languageclient/blob/main/docs/versions-and-history.md) to upgrade the packages version related to the monaco editor and language client.
+
 ### Code of Conduct
 
 We are committed to fostering a welcoming and inclusive environment.

README.md

@@ -1,50 +1,56 @@
-# YASGUI
+# SPARQL Studio
+
+SPARQL Studio is a SPARQL query editor and results viewer for the web. It is a fork of [Yasgui](https://github.com/zazuko/Yasgui) and stays compatible with all existing Yasr result-view plugins.
 
 Useful links:
 
-- User documentation: https://docs.triply.cc/yasgui/
-- Developer documentation: https://docs.triply.cc/yasgui-api/
-- Documentation Github repository (feel free to add a PR for improvements): https://github.com/TriplyDB/Documentation
+- Live demo: [sparql.studio](https://sparql.studio)
+- Documentation: [sparql.studio/docs/introduction](https://sparql.studio/docs/introduction)
+- Source code: [github.com/rdfjs/Yasgui](https://github.com/rdfjs/Yasgui)
+
+## Packages
+
+| Package                            | Description                                            |
+| ---------------------------------- | ------------------------------------------------------ |
+| `@rdfjs/sparql-studio`             | Full app: tabbed editor + results (formerly Yasgui)    |
+| `@rdfjs/sparql-editor-monaco`      | SPARQL query editor based on Monaco (formerly Yasqe)   |
+| `@rdfjs/sparql-editor-codemirror`  | SPARQL query editor based on CodeMirror 6              |
+| `@rdfjs/sparql-results`            | SPARQL results viewer (formerly Yasr)                  |
+| `@rdfjs/sparql-utils`              | Shared utilities                                       |
 
 ## Installation
 
-Below are instructions on how to include Yasgui in your project.
-If you only want to install Yasr or Yasqe, replace yasgui in the commands below.
+Below is how to include the full app in your project. To install only the editor or the
+results viewer, swap `@rdfjs/sparql-studio` for the relevant package above.
 
 ### npm
 
 ```sh
-npm i @zazuko/yasgui
+npm i @rdfjs/sparql-studio
 ```
 
 ### Yarn
 
 ```sh
-yarn add @zazuko/yasgui
+yarn add @rdfjs/sparql-studio
 ```
 
 ## Local development
 
-#### Installing dependencies
+### Installing dependencies
 
 Run `npm install`.
 
-#### Running Yasgui locally
-
-To develop locally, run `npm run dev`
+### Running locally
 
-#### Compiling Yasgui
+To develop locally, run `npm run dev`.
 
-Run `npm run build`. It'll store the transpiled js/css files in the `build` directory.
+### Compiling
 
-Update prefixes from http://prefix.cc:
-
-```sh
-npm run util:prefixes
-```
+Run `npm run build`. It stores the transpiled js/css files in the `build` directory.
 
 ## License
 
-This is a fork from Zazuko from software written by Triply.
+SPARQL Studio is a fork of [Yasgui](https://github.com/TriplyDB/Yasgui/) maintained by Zazuko, originally written by Triply.
 
 This code is released under the MIT license.

dev/codemirror.html

@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" href="/sparql-studio.svg" />
+    <link rel="stylesheet" href="./style.css" />
+    <title>SPARQL Studio · CodeMirror</title>
+  </head>
+  <body>
+    <div class="navBar">
+      <nav style="display: flex">
+        <img class="logo" src="/sparql-studio.svg" style="max-height:50px;padding:5px;margin-left: 10px" alt="SPARQL Studio Logo" />
+        <ul style="display: flex; list-style: none; align-self: center">
+          <li class="navItem"><a class="nav-link" href="/">SPARQL Studio</a></li>
+          <li class="navItem active"><a class="nav-link" href="codemirror">CodeMirror</a></li>
+          <li class="navItem"><a class="nav-link" href="editor_results">Editor & Results</a></li>
+        </ul>
+        <button class="themeToggle" id="darkModeToggle" type="button"></button>
+      </nav>
+    </div>
+
+    <div id="sparqlStudio"></div>
+
+    <script type="module">
+      import SparqlStudio from "@rdfjs/sparql-studio";
+      import SparqlEditor from "@rdfjs/sparql-editor-codemirror";
+      import { qlueLs } from "@rdfjs/sparql-utils";
+      import QlueLsWorker from "./qluels.worker?worker";
+      import SwlsWorker from "./swls.worker?worker";
+      import TraqulaWorker from "./traqula.worker?worker";
+      import { setupThemeToggle, DEMO_ENDPOINT } from "./utils";
+
+      const theme = setupThemeToggle((t) => window.sparqlStudio.editor?.setTheme(t));
+
+      const endpointOf = () => window.sparqlStudio?.getTab()?.getEndpoint() ?? DEMO_ENDPOINT;
+      const onReady = (conn) => {
+        qlueLs.configureSettings(conn, qlueLs.defaultSettings);
+        qlueLs.configureBackend(conn, endpointOf());
+      };
+      const onEndpointChange = (conn, endpoint) => qlueLs.configureBackend(conn, endpoint);
+
+      window.sparqlStudio = new SparqlStudio(document.getElementById("sparqlStudio"), {
+        requestConfig: { endpoint: DEMO_ENDPOINT },
+        editor: (parent, conf) =>
+          new SparqlEditor(parent, {
+            ...conf,
+            theme,
+            languageServers: [
+              {
+                label: "Qlue-ls",
+                description: "SPARQL language server with endpoint-powered completions",
+                worker: () => new QlueLsWorker({ name: "qlue-ls" }),
+                onReady,
+                onEndpointChange,
+                configSchema: qlueLs.settingsSchema,
+                configCallback: (conn, settings) => qlueLs.configureSettings(conn, settings),
+              },
+              {
+                label: "swls",
+                description: "Semantic web language server",
+                worker: () => new SwlsWorker({ name: "swls" }),
+              },
+              {
+                label: "Traqula",
+                description: "JS SPARQL 1.2 parser (diagnostics only)",
+                worker: () => new TraqulaWorker({ name: "traqula-ls" }),
+              },
+            ],
+          }),
+      });
+    </script>
+  </body>
+</html>

dev/editor_results.html

@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" href="/sparql-studio.svg" />
+    <link rel="stylesheet" href="./style.css" />
+    <title>SPARQL Editor & Results</title>
+  </head>
+  <body>
+    <div class="navBar">
+      <nav style="display: flex">
+        <img class="logo" src="/sparql-studio.svg" style="max-height:50px;padding:5px;margin-left: 10px" alt="SPARQL Studio Logo" />
+        <ul style="display: flex; list-style: none; align-self: center">
+          <li class="navItem"><a class="nav-link" href="/">SPARQL Studio</a></li>
+          <li class="navItem"><a class="nav-link" href="codemirror">CodeMirror</a></li>
+          <li class="navItem active"><a class="nav-link" href="editor_results">Editor & Results</a></li>
+        </ul>
+        <button class="themeToggle" id="darkModeToggle" type="button"></button>
+      </nav>
+    </div>
+    <div id="sparqlEditor"></div>
+    <div id="sparqlResults"></div>
+    <script type="module">
+      import SparqlEditor, { qlueLs } from "@rdfjs/sparql-editor-monaco";
+      import SparqlResults from "@rdfjs/sparql-results";
+      import QlueLsWorker from "./qluels.worker?worker";
+      import { setupThemeToggle, DEMO_ENDPOINT } from "./utils";
+
+      window.onpageshow = function () {
+        const theme = setupThemeToggle((t) => window.sparqlEditor?.setTheme(t));
+        window.sparqlEditor = new SparqlEditor(document.getElementById("sparqlEditor"), {
+          theme,
+          languageServers: [
+            {
+              label: "Qlue-ls",
+              worker: () => new QlueLsWorker({ name: "qlue-ls" }),
+              onReady: (client) => qlueLs.configureBackend(client, DEMO_ENDPOINT),
+            },
+          ],
+        });
+        window.sparqlResults = new SparqlResults(document.getElementById("sparqlResults"), {
+          prefixes: function () {
+            return window.sparqlEditor.getPrefixesFromQuery();
+          },
+        });
+        window.sparqlEditor.on("queryResponse", function (sparqlEditor, response, duration) {
+          console.log({ response: response });
+          window.sparqlResults.setResponse(response, duration);
+        });
+      };
+    </script>
+  </body>
+</html>