Skip to content
mightymaxPublic

About

Composable TypeScript SPARQL IDE with virtual tabs, contextual completion and extensible actions and renderers

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

62 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

LDForge

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 demo

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 dev

Open 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.

One HTML file, no build step

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.

Packages

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.

Embed the editor

Install the public ESM packages from npm:

npm install @ldforge/core @ldforge/editor @ldforge/renderers @ldforge/prefixes

Use 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.

SPARQL assistance and prefixes

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.

Development and tests

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.

Current scope

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.

License

Licensed under the MIT License, SPDX identifier MIT. Full license text is included in each library package. Third-party dependencies retain their own licenses.

Optional geodata

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.

Optional charts

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.

Toolbar groups and dropdowns

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.

Hosting and deployment

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.

Network and timeline renderers

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.

Pivot renderer

@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.

Migrating from Yasgui

@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.

Independent package releases

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.

About

Composable TypeScript SPARQL IDE with virtual tabs, contextual completion and extensible actions and renderers

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages