Composable, framework-independent SPARQL tooling, designed to bring the LDMax editor into other applications. This repository establishes the standalone architecture; the existing LDMax implementation has not yet been migrated.
LDForge separates query execution, editor actions, and result presentation. It uses TypeScript in strict mode, CodeMirror 6 for query editing, and explicit plugin registration without global state.
Try the live demo at ldforge.nl — editor, plugin examples and API documentation.
Requires Node.js 22.12 or newer and npm. No backend, account, environment variables, or external endpoint is required.
npm ci
npm run devOpen the local URL printed by Vite. Run the example SELECT query, switch between Table and JSON, or use the ASK example button. Fixture mode returns deterministic sample data; it does not evaluate SPARQL.
The demo initially folds PREFIX declarations, including restored tabs and newly selected example queries. Use the gutter arrow or folded placeholder to expand them.
Under Examples → Gallery, load the Wikidata cats query and press Run query to show twelve cat cards. Choosing this example selects Wikidata over GET, without reusing another connection's headers. That endpoint remains selected until you change it in settings; choose Local fixture (no endpoint) to return to offline examples.
Use the gear button inside the IDE to manage endpoints. The overview lists saved connections and the local fixture. Add endpoint opens a separate form for the URL, GET/POST method and optional headers. Save endpoint stores a new connection without selecting it; select its radio button to use it. Edit endpoint opens an existing profile. Saving changes to the active profile updates that connection; editing another profile keeps the current selection. Cancel discards the draft. Changing a draft's URL clears its headers so credentials are not carried to a different recipient.
Endpoint URLs and methods are saved in browser localStorage. Header values remain in memory for this page only and are isolated per endpoint. Browser CORS rules still apply. The demo restores the selected endpoint and method after a refresh without running a query. Select Local fixture (no endpoint) to return to example data. The active URL below the editor uses a code font; its clipboard button copies just the URL and briefly shows a checkmark.
The demo starts with a fixed 15-line query viewport and scrolls longer queries internally. Show the full query under Settings lets the editor grow with the query; the demo remembers this preference. Integrations configure editorRows and autoGrow, or use setEditorRows() and setAutoGrow(). The library defaults to 15 rows with auto-grow enabled.
Table and JSON stay on the result bar by default. Other registered views appear in Choose view, disabled when unsuitable; each dropdown entry has a binding-contract information button. The active view also remains on the bar. Configure visiblePlugins / availablePlugins, or call showPlugin(), hidePlugin(), showAvailablePlugins() and hideAvailablePlugins() at runtime. If # view=… requests an unsupported view, a warning explains the mismatch and lists missing declared required bindings. JSON uses read-only CodeMirror syntax highlighting with a copy button and confirmation. The share-link tool uses a share icon.
Create queries with +, switch tabs, and rename a tab by double-clicking its name or using its pencil button. Enter or leaving the name field saves it; Escape cancels. Query text, titles, and the active tab are saved to localStorage when editing or switching. There is one CodeMirror view and one active editor state: inactive tabs store plain text only. Switching cancels a running query and resets undo history and results.
The IDE follows the first supported browser language (English or Dutch), with English fallback. A project can set locale; a user choice under the gear button takes precedence and is remembered by the demo. Demo introduction and integration documentation remain in English. Query completion reports a compact count and elapsed execution time, such as 3 results in 124 ms or 3 resultaten in 1,25 s.
Try the live Wikidata cat grid, or copy
examples/wikidata-cats.html to your own static site.
It loads the published 0.1.2 JavaScript packages from esm.sh with
?standalone and the stylesheet from jsDelivr, executes a real Wikidata query
over GET, and renders the results with createCardsRenderer(). No import map,
npm install, Node server, API key, or framework is needed. Serve the file over
HTTP(S), for example with python3 -m http.server 8080 --directory examples.
Use https://esm.sh/@ldforge/editor@0.1.2?standalone for the browser-ready
editor: the CDN bundles its dependencies together, keeping CodeMirror on a single
instance. The example pins all LDForge imports to the same version. Change those
URLs together when upgrading and run npm run test:cdn to verify the real CDN
integration. CDN access and the public endpoint require an internet connection.
# view=cards selects the renderer; card_title, card_text, card_image,
card_button and card_button_url supply each card.
| Package | Responsibility |
|---|---|
@ldforge/core |
RDF result types, plugin contracts, registry, query lifecycle, and HTTP executor; no DOM runtime dependency |
@ldforge/editor |
CodeMirror editor, button plugins, keyboard shortcut, result plugin selection, lifecycle and styles |
@ldforge/prefixes |
Curated common namespace catalog, ready-to-use map and search helper |
@ldforge/renderers |
Independent table, cards, boolean, and normalized JSON renderers |
@ldforge/charts |
Optional chart renderer; external Chart.js runtime loaded only on activation |
@ldforge/geo |
Optional map renderer with normal, grouped and heatmap views; external libraries loaded on demand |
apps/demo |
Minimal Vite host with fixture/live execution and custom action plugins |
The editor depends on core, CodeMirror and the prefix catalog. Default result renderers are supplied by the host, so another application can use its own rendering stack.
Install the public ESM packages from npm:
npm install @ldforge/core @ldforge/editor @ldforge/renderers @ldforge/prefixesUse a browser bundler with CSS imports. Complete configuration and object references are available in the demo's API reference and in docs/api. Maintainers should follow the separate npm publishing guide.
import { createHttpExecutor } from '@ldforge/core';
import { createEditor } from '@ldforge/editor';
import {
createTableRenderer,
createBooleanRenderer,
createJsonRenderer,
} from '@ldforge/renderers';
import '@ldforge/editor/styles.css';
const container = document.querySelector<HTMLElement>('#query-editor');
if (!container) throw new Error('Missing editor container');
const editor = createEditor(container, {
query: 'SELECT * WHERE { ?s ?p ?o } LIMIT 10',
executor: createHttpExecutor({
endpoint: 'https://your-endpoint.example/sparql',
}),
renderers: [
createTableRenderer(),
createBooleanRenderer(),
createJsonRenderer(),
],
});
// Call when your host component unmounts:
// editor.destroy();The host owns endpoint configuration and authentication. Inject a QueryExecutor for a backend proxy, fixtures, or custom transport. Inject fetch or headers into createHttpExecutor for host-specific HTTP behavior. Never put private server credentials in a browser bundle.
The editor uses a SPARQL Lezer grammar for syntax trees, highlighting, local diagnostics and completion. Press Ctrl+Space for suggestions. Predicates are offered in predicate/path positions, variables come from previous syntactic occurrences in the visible query scope, and comments, strings and IRI contents are excluded. SERVICE, FILTER, nested triples, semicolon and comma positions are recognized structurally. These are local editor features, not a language-server integration or a guarantee of semantic query correctness.
Choosing a predicate completion inserts any missing PREFIX in the same undoable edit. Existing aliases are reused; conflicting names receive a suffix. Known undeclared prefixes have a diagnostic quick fix. Use Prefixes in the toolbar to search and insert namespaces without completing a predicate.
import { prefixes, searchPrefixes } from '@ldforge/prefixes';
searchPrefixes('prov');
// In createEditor options:
// sparql: {
// prefixes: { ...prefixes, ex: 'https://example.org/' },
// autoPrefixes: false, // Optional: disable automatic declarations while typing.
// predicates: [{ iri: 'https://example.org/name', description: 'Name' }],
// }The prefix package has a compact catalog (32 mappings, the default) and an extended catalog (3,623 mappings). Import prefixes from @ldforge/prefixes/compact or @ldforge/prefixes/extended and pass it as sparql: { prefixes }. Entries contain only prefix and namespace, without labels. Compact imports do not load the extended data. Neither catalog makes network requests. Omit predicates to use the small built-in RDF vocabulary, or provide your own project vocabulary. Prefix names and namespace HTTP/HTTPS identifiers are preserved exactly. Toolbar actions can set a group identifier to form compact button groups. Prefix search, formatting and settings are icon-only core tools on the right; host actions are separated. Use controls to toggle every built-in control without disabling its API.
npm run typecheck # Strict TypeScript across packages, demo and tests
npm run lint # ESLint
npm run format:check # Prettier
npm test # Unit and DOM integration tests
npm run test:coverage # Enforced coverage thresholds and HTML report
npm run build # ESM libraries, declarations, source maps and demo
npm run test:docs # Typecheck the complete documented API example
npm run test:packages # Install real tarballs and typecheck an isolated consumer
npx playwright install chromium
npm run test:e2e # Real-browser demo tests
npm run check # All of the above checks (browser must be installed)Results use accessible icon tabs and provide a CSV download for SELECT, ASK and RDF graph results. Plugins can supply optional icon factories and documentationUrl links to their usage and binding guides; set controls: { download: false } to hide export.
The Cards renderer maps card_title, card_text, card_image, card_button and card_button_url to a responsive card grid. Leading query comments such as # view=cards and # css=max-width: 320px; control the result view and individual card styling. See the binding and header guide.
The demo includes a Plugins page describing each built-in renderer and its binding contract. Build with npm run build and serve apps/demo/dist/ on any static host; relative assets and navigation support subdirectories.
See the configuration reference, editor API, tab API, npm publishing guide, plugin authoring, architecture, language and editor evaluation, testing, and contributing.
This is a working foundation, not feature parity with LDMax. SELECT/ASK and CONSTRUCT/DESCRIBE, cancellation, syntax highlighting, history, Lezer-based syntax diagnostics and contextual completion, custom buttons, settings plugins, EN/NL localization, virtual query tabs, execution timing, and interchangeable result renderers are included. SPARQL Update execution, endpoint-backed vocabulary discovery, full semantic query validation, and migration of LDMax-specific behavior are follow-up work. The table renderer supports sorting, filters, virtual scrolling for large results, and a resource inspector. Results remain in memory; hosts should still limit very large queries.
Licensed under the MIT License, SPDX identifier MIT. Full license text is included in each library package. Third-party dependencies retain their own licenses.
Register createGeoRenderer() from @ldforge/geo to visualize WKT points, lines and polygons from ?geometry with optional ?geometryLabel. Leaflet JavaScript and CSS load externally only when the Map tab opens. See the geo guide for OpenStreetMap and mixed-geometry examples and self-hosting options.
Install @ldforge/charts and register createChartRenderer() to enable charts using chart_label, chart_value and optional chart_series bindings. The default loader fetches a pinned external Chart.js ESM module only when the Charts tab opens, keeping Chart.js out of the application bundle. Set loadLibrary: () => import('chart.js/auto') to use a self-hosted lazy chunk instead (install Chart.js in the host). See the chart binding and loading guide for headers, validation and deployment options.
Existing action groups remain adjacent buttons by default. Configure toolbar.groups: [{ id: 'examples', type: 'dropdown', label: 'Example queries' }] to collapse that custom group into a menu. Use editor.getToolBar() to add standalone actions, create reusable button handles or build/change groups at runtime. See the Toolbar API for every object, method and keyboard behavior. The demo website at ldforge.nl opts into two runtime-created dropdowns: Query Examples and Plugin Examples. Library defaults remain unchanged.
The built demo is static HTML/CSS/JavaScript. Use the deployment guide for container builds, Kubernetes/Helm, Argo CD and optional per-installation analytics. Public defaults contain no tracking ID; local operator values belong under the gitignored .local/ directory or in a private GitOps repository.
After one-time GitOps setup, npm run release can also deploy the website after selectively publishing the planned npm packages. Deploy only the site with gh workflow run website.yml --ref main -f source_ref=main; no npm version or release tag is created. See automated website releases.
Optional @ldforge/network and @ldforge/timeline packages add interactive
relationship graphs and dated events/ranges. Their visual libraries are downloaded
only when their result tab opens. Try Nederlandse schilders en hun relaties
(netwerk) and Levens van Nederlandse schilders (tijdlijn) in the demo's
Examples menu; both query the public Wikidata endpoint. See the
renderer guide for the binding contracts and options.
@ldforge/pivot adds native, accessible pivot tables with sum/count/average/min/max,
correct totals, axis sorting/transposition and cell colors. It needs no external
visualization library. Try Kunststromingen per collectie (draaitabel) on the demo
or read the pivot contract and example.
@ldforge/tree adds accessible lazy hierarchy exploration for SKOS, class and organizational structures. Register createTreeRenderer() and select # view=tree; see the tree binding contract and examples.
@ldforge/yasgui provides a separate compatibility
module. Replace your Yasgui JavaScript and stylesheet imports while retaining
new Yasgui(element, options), common request options, tab methods and events.
It includes a standalone browser bundle exposing window.Yasgui and a
script-tag example. See the module's compatibility
matrix for supported methods and the boundaries around Yasqe/Yasr extensions.
Commit package changes with a .changeset/*.md description (npm run changeset).
Inspect the read-only package/version plan with npm run release:plan. On clean
main, npm run release:prepare creates a local version/changelog commit and batch
and package tags; npm run release:push atomically pushes them to start CI
publication. npm run release combines preparation and push. These last commands
start real releases; planning, builds and tests do not publish.
Only affected packages and necessary dependents are published. The standalone
Yasgui bundle is included automatically for changes in its embedded packages.
Root/workspace npm version is blocked. All versions remain at their existing
published values until a planned release is prepared. See Publishing
for prereleases, minimum-version compatibility checks, website-only deployment
and recovery of both new batches and historical releases.