@ldforge/editor 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +21 -0
  2. package/dist/controls.d.ts +3 -0
  3. package/dist/controls.d.ts.map +1 -1
  4. package/dist/controls.js +3 -0
  5. package/dist/controls.js.map +1 -1
  6. package/dist/font-size.d.ts +8 -0
  7. package/dist/font-size.d.ts.map +1 -0
  8. package/dist/font-size.js +41 -0
  9. package/dist/font-size.js.map +1 -0
  10. package/dist/index.d.ts +14 -2
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +106 -9
  13. package/dist/index.js.map +1 -1
  14. package/dist/renderer-header.d.ts +10 -0
  15. package/dist/renderer-header.d.ts.map +1 -0
  16. package/dist/renderer-header.js +100 -0
  17. package/dist/renderer-header.js.map +1 -0
  18. package/dist/renderer-wizard.d.ts +31 -0
  19. package/dist/renderer-wizard.d.ts.map +1 -0
  20. package/dist/renderer-wizard.js +363 -0
  21. package/dist/renderer-wizard.js.map +1 -0
  22. package/dist/styles.css +183 -1
  23. package/dist/toolbar-types.d.ts +4 -0
  24. package/dist/toolbar-types.d.ts.map +1 -1
  25. package/dist/toolbar.d.ts.map +1 -1
  26. package/dist/toolbar.js +45 -11
  27. package/dist/toolbar.js.map +1 -1
  28. package/docs/api/configuration.md +23 -3
  29. package/docs/api/editor.md +68 -0
  30. package/docs/api/plugins.md +57 -0
  31. package/docs/api/prefixes.md +2 -0
  32. package/docs/api/toolbar.md +26 -2
  33. package/docs/api/transport.md +38 -0
  34. package/docs/renderers.md +519 -23
  35. package/package.json +3 -3
  36. package/src/controls.ts +6 -0
  37. package/src/font-size.ts +57 -0
  38. package/src/index.ts +132 -10
  39. package/src/renderer-header.ts +122 -0
  40. package/src/renderer-wizard.ts +400 -0
  41. package/src/styles.css +183 -1
  42. package/src/toolbar-types.ts +4 -0
  43. package/src/toolbar.ts +57 -14
package/docs/renderers.md CHANGED
@@ -16,10 +16,14 @@ const renderers = [createTableRenderer(), createGeoRenderer()];
16
16
 
17
17
  ### Geo binding contract
18
18
 
19
- | Variable | Required | Meaning |
20
- | ---------------- | -------- | ------------------------------------------------------------------------------- |
21
- | `?geometry` | Yes | Literal containing two-dimensional WGS84 WKT; longitude first, latitude second. |
22
- | `?geometryLabel` | No | Plain-text feature label, defaults to the result row number. |
19
+ | Variable | Required | Meaning |
20
+ | ----------------- | -------- | ------------------------------------------------------------------------------- |
21
+ | `?geometry` | Yes | Literal containing two-dimensional WGS84 WKT; longitude first, latitude second. |
22
+ | `?geometryLabel` | No | Plain-text feature label, defaults to the result row number. |
23
+ | `?geometryHeight` | No | Nonnegative numeric literal in meters; extrudes polygons in 3D. |
24
+ | `?geoImage` | No | Absolute HTTP(S) image URI or URL literal, shown in the feature popup. |
25
+ | `?geoDescription` | No | Plain-text popup description, with line breaks preserved. |
26
+ | `?geoLink` | No | Absolute HTTP(S) URI or URL literal; makes the label a link in a new tab. |
23
27
 
24
28
  The tab appears for results declaring `geometry`. Use `# view=geo` to activate it automatically and optional `geo-title` for its heading. `POINT`, `LINESTRING`, `POLYGON` (including holes), `MULTIPOINT`, `MULTILINESTRING` and `MULTIPOLYGON` are supported, including mixed types in one result. Bare WKT and the GeoSPARQL CRS84 URI prefix are accepted. Other CRS/SRID values, extra dimensions, EMPTY and geometry collections are rejected rather than projected or guessed. Coordinate bounds, finite numbers, minimum lengths and closed rings are checked; polygon topology is not checked. Invalid or unbound geometries produce a localized row error; empty results show an empty state without loading external assets.
25
29
 
@@ -29,31 +33,93 @@ The compact button group offers **Normal**, **Grouped**, and **Heatmap** (locali
29
33
 
30
34
  Choose the initial mode with `# view=geo; mode=grouped` or `mode=heatmap`; the host option `mode` supplies the default. `geo-mode` remains supported as an alias; `mode` takes precedence when both are supplied. Invalid mode directives fall back to Normal. Switching modes preserves map position. Supercluster 8.0.1 and simpleheat 0.4.0 are separate pinned external ESM downloads that happen only when that mode is first selected. Configure `clusterLibraryUrl`/`heatLibraryUrl` or inject `loadClusterLibrary`/`loadHeatLibrary` for self-hosting. Failed mode loads can be retried; late completions after another selection or cleanup cannot replace the active view. Supercluster is ISC licensed and simpleheat is BSD-2-Clause licensed.
31
35
 
32
- ### OpenStreetMap example
36
+ ### 3D buildings
33
37
 
34
- Endpoint: `https://api.triplydb.com/datasets/osm/osm/services/osm/sparql` (GET). This query retrieves features tagged `leisure=track` with their WKT geometry and an optional name, falling back to “Atletiekbaan”. It starts in Heatmap mode and has no sport filter or result limit. The demo's **Map example (athletics tracks)** selects this endpoint and query.
38
+ Bind `?geometryHeight` to a finite, nonnegative number in meters. Polygons and
39
+ MultiPolygons retain their holes and extrude upward from ground level. Missing
40
+ heights leave a polygon flat; points and lines remain visible. Invalid bound
41
+ heights produce a row error. WKT remains two-dimensional longitude/latitude data.
42
+
43
+ Positive polygon heights default to **3D**, unless `mode`/`geo-mode` or the host
44
+ `mode` option explicitly chooses another mode. To always select 3D, use
45
+ `# view=geo; mode=3d`. The 3D button uses MapLibre GL JS 6.18.0 (BSD-3-Clause),
46
+ loaded from a pinned external module with matching CSS only when needed. Normal,
47
+ Grouped and Heatmap continue to use Leaflet without downloading MapLibre.
48
+
49
+ The demo's **Paleis het Loo (Geo 3D)** example uses the OSM endpoint below:
35
50
 
36
51
  ```sparql
37
- # view=geo; mode=heatmap; geo-title=Atletiekbanen in Nederland
38
- PREFIX geo: <http://www.opengis.net/ont/geosparql#>
52
+ # view=geo; mode=3d; geo-title=Paleis het Loo
39
53
  PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
54
+ PREFIX geo: <http://www.opengis.net/ont/geosparql#>
40
55
  PREFIX osmt: <https://data.osm.pldn.nl/wiki/Key:>
41
- PREFIX track: <https://data.osm.pldn.nl/wiki/Tag:leisure=track>
42
- PREFIX athletics: <https://data.osm.pldn.nl/wiki/Tag:sport=athletics>
56
+ SELECT * WHERE {
57
+ ?gebouw osmt:building ?building .
58
+ ?gebouw skos:prefLabel ?geometryLabel .
59
+ ?gebouw geo:hasGeometry/geo:asWKT ?geometry .
60
+ BIND(10 AS ?geometryHeight)
61
+ FILTER(?geometryLabel = "Paleis het Loo")
62
+ }
63
+ ```
43
64
 
44
- SELECT ?place ?geometryLabel ?geometry WHERE {
45
- ?place osmt:leisure track: ;
46
- geo:hasGeometry/geo:asWKT ?geometry .
65
+ This makes a ten-meter building volume, not a detailed roof or architectural
66
+ model. The tilted view fits query bounds. Navigation controls and right-drag
67
+ allow rotation/tilt. Click a feature for its label and height. Returning to a
68
+ Leaflet mode restores the 2D view. WebGL is required; on failure, retry or choose
69
+ Normal. Text geometry/height data stays available. Self-host using
70
+ `threeDLibraryUrl`, `threeDStylesheetUrl` (or `false` for host CSS), and
71
+ `loadThreeDLibrary`. The exported `ThreeDLibrary`, `ThreeDMapHandle` and
72
+ `ThreeDMapEvent` types require no installed MapLibre type dependency. The usual
73
+ `tileUrl`/`tileAttribution` options apply in both renderers, including
74
+ `tileUrl: false`. Allow `worker-src blob:` in CSP for MapLibre's worker.
75
+
76
+ ### Castles in North Holland example
77
+
78
+ Endpoint: `https://query.wikidata.org/sparql` (GET). The demo's **Kastelen in Nederland (Geo)**
79
+ returns up to 250 castles in North Holland with coordinates and a Wikidata image. It uses
80
+ mandatory patterns without OPTIONAL, including a Dutch Wikipedia sitelink. Only castles
81
+ with a Dutch article appear. Popup labels link to that Wikipedia article; descriptions
82
+ prefer Dutch and fall back to English. Commons images use HTTPS thumbnail URLs.
83
+ The missing `rdfs` and `schema` prefixes are included explicitly.
47
84
 
48
- OPTIONAL {
49
- ?place skos:prefLabel ?name .
85
+ ```sparql
86
+ # view=geo; geo-title=Kastelen in Noord-Holland
87
+ PREFIX wd: <http://www.wikidata.org/entity/>
88
+ PREFIX wdt: <http://www.wikidata.org/prop/direct/>
89
+ PREFIX wikibase: <http://wikiba.se/ontology#>
90
+ PREFIX bd: <http://www.bigdata.com/rdf#>
91
+ PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
92
+ PREFIX schema: <http://schema.org/>
93
+
94
+ SELECT ?place ?geometryLabel ?geoDescription ?geoImage ?geometry ?geoLink WHERE {
95
+ ?place wdt:P31 wd:Q23413 ;
96
+ wdt:P17 wd:Q55 ;
97
+ wdt:P131+ wd:Q701 ;
98
+ wdt:P625 ?geometry ;
99
+ wdt:P18 ?image .
100
+
101
+ ?geoLink schema:about ?place ;
102
+ schema:isPartOf <https://nl.wikipedia.org/> .
103
+
104
+ SERVICE wikibase:label {
105
+ bd:serviceParam wikibase:language "nl,en" .
106
+ ?place rdfs:label ?geometryLabel ;
107
+ schema:description ?geoDescription .
50
108
  }
51
109
 
52
- BIND(COALESCE(?name, "Atletiekbaan") AS ?geometryLabel)
110
+ BIND(IRI(CONCAT(REPLACE(STR(?image), "^http:", "https:"), "?width=480")) AS ?geoImage)
53
111
  }
112
+ LIMIT 250
54
113
  ```
55
114
 
56
- The source supplies geometry through `geo:hasGeometry/geo:asWKT`. Other projections must first be converted to WGS84/CRS84.
115
+ Wikipedia sitelinks are modeled from the article to the Wikidata item:
116
+ `?geoLink schema:about ?place`. The additional
117
+ `schema:isPartOf <https://nl.wikipedia.org/>` selects Dutch Wikipedia rather than
118
+ another language or Wikimedia project. This is a sitelink, not a `wdt:P…`
119
+ statement on the castle. See the [Wikibase RDF sitelink format](https://www.mediawiki.org/wiki/Wikibase/Indexing/RDF_Dump_Format#Sitelinks).
120
+
121
+ Wikidata's `wdt:P625` returns WGS84 WKT points directly, so no geometry conversion
122
+ is needed. The separate **Paleis het Loo (Geo 3D)** example above keeps using OSM.
57
123
 
58
124
  This deterministic query demonstrates all three basic types on any SPARQL 1.1 endpoint:
59
125
 
@@ -74,6 +140,273 @@ See [GeoRendererOptions and supported WKT](https://github.com/mightymax/ldforge/
74
140
 
75
141
  External mode requires network access and CSP permissions for CDN scripts/styles and tile images. Leaflet is BSD-2-Clause licensed. The default tiles follow the [OpenStreetMap tile usage policy](https://operations.osmfoundation.org/policies/tiles/); use a suitable provider for production traffic. Only trusted host configuration can specify executable library URLs or attribution HTML; query comments cannot. Module/CSS failures show a retry button. Tile failures are handled by Leaflet and do not remove geometry. An expandable text geometry list remains accessible. Cleanup removes maps and resize observers and ignores late asynchronous completions.
76
142
 
143
+ ## Network
144
+
145
+ **Package:** `@ldforge/network` (optional) · **Factory:** `createNetworkRenderer(options?)` · **ID:** `network`
146
+
147
+ Interactive directed relationship graphs using vis-network 10.1.5, loaded from a
148
+ pinned external ESM module only when the Network tab opens. The library is not
149
+ bundled or a package runtime dependency. Register it alongside other renderers:
150
+
151
+ ```ts
152
+ import { createNetworkRenderer } from '@ldforge/network';
153
+ const renderers = [createTableRenderer(), createNetworkRenderer()];
154
+ ```
155
+
156
+ | Binding | Required | Meaning |
157
+ | ------------------------------ | -------- | ------------------------------------------------------------------------------ |
158
+ | `?source`, `?target` | Yes | URI or blank-node identifiers. Literals and missing nodes produce a row error. |
159
+ | `?sourceLabel`, `?targetLabel` | No | Plain-text names; fall back to each identifier. |
160
+ | `?relationLabel` | No | Plain-text directed edge label. |
161
+ | `?sourceGroup`, `?targetGroup` | No | Group names used for node colors and the legend. |
162
+
163
+ A node is identified by its RDF term type and value. Repeated nodes and identical
164
+ source/target/label edges are deduplicated; different relation labels stay separate.
165
+ Use consistent group names for a node across rows. URI nodes have a safe HTTP(S)
166
+ link in the selected-node panel and the always-available Network data list; blank
167
+ nodes and unsafe URL schemes remain plain text. No labels are interpreted as HTML.
168
+
169
+ Use `# view=network; network-title=My graph`. Drag nodes/background, zoom, select a
170
+ node to highlight its connected edges, or use the labeled node picker to focus a
171
+ node and expose its link. Fit/zoom buttons are available. Arrow keys and +/- work
172
+ while the network canvas is focused; they do not capture keys globally.
173
+
174
+ Options: `libraryUrl` defaults to
175
+ `https://cdn.jsdelivr.net/npm/vis-network@10.1.5/standalone/esm/vis-network.min.mjs`;
176
+ `loadLibrary` supplies a custom lazy loader exporting `Network` with the exported
177
+ `NetworkConstructor`/`NetworkHandle` interfaces. Optional `stylesheetUrl` loads
178
+ host CSS (or `false` disables it); the default standalone build includes its own
179
+ styles. vis-network is dual Apache-2.0/MIT licensed. Only trusted host options can
180
+ change executable asset URLs. Failed downloads/module exports can be retried;
181
+ late loads after cleanup never create a network. Cleanup calls `destroy()`.
182
+
183
+ ### Dutch painters example
184
+
185
+ Public endpoint: `https://query.wikidata.org/sparql` (GET). Both Netherlands and
186
+ Kingdom of the Netherlands citizenship values are included. The bounded query
187
+ returns up to 75 teacher/movement relations with Dutch labels, falling back to
188
+ English. Values reflect Wikidata's current statements, not a curated art history.
189
+
190
+ ```sparql
191
+ # view=network; network-title=Nederlandse schilders, leermeesters en kunststromingen
192
+ PREFIX wd: <http://www.wikidata.org/entity/>
193
+ PREFIX wdt: <http://www.wikidata.org/prop/direct/>
194
+ PREFIX wikibase: <http://wikiba.se/ontology#>
195
+ PREFIX bd: <http://www.bigdata.com/rdf#>
196
+ PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
197
+
198
+ SELECT ?source ?sourceLabel ?target ?targetLabel ?relationLabel ?sourceGroup ?targetGroup WHERE {
199
+ {
200
+ SELECT DISTINCT ?source ?target ?relationLabel ?targetGroup WHERE {
201
+ VALUES ?country { wd:Q55 wd:Q29999 }
202
+ ?source wdt:P27 ?country ;
203
+ wdt:P106/wdt:P279* wd:Q1028181 .
204
+ {
205
+ ?source wdt:P135 ?target .
206
+ BIND("kunststroming" AS ?relationLabel)
207
+ BIND("Kunststroming" AS ?targetGroup)
208
+ }
209
+ UNION
210
+ {
211
+ ?source wdt:P1066 ?target .
212
+ BIND("leermeester" AS ?relationLabel)
213
+ BIND("Kunstenaar" AS ?targetGroup)
214
+ }
215
+ }
216
+ LIMIT 75
217
+ }
218
+ BIND("Kunstenaar" AS ?sourceGroup)
219
+ SERVICE wikibase:label {
220
+ bd:serviceParam wikibase:language "nl,en" .
221
+ ?source rdfs:label ?sourceLabel .
222
+ ?target rdfs:label ?targetLabel .
223
+ }
224
+ }
225
+ ```
226
+
227
+ ## Timeline
228
+
229
+ **Package:** `@ldforge/timeline` (optional) · **Factory:** `createTimelineRenderer(options?)` · **ID:** `timeline`
230
+
231
+ Interactive dated points and ranges with vis-timeline 8.5.6, downloaded only when
232
+ the Timeline tab opens. Supports grouping, dragging through time, Ctrl + scroll
233
+ to zoom, explicit zoom buttons and a Fit action. Large overlapping sets can be
234
+ scrolled vertically. Events are read-only; dragging does not edit source data.
235
+
236
+ ```ts
237
+ import { createTimelineRenderer } from '@ldforge/timeline';
238
+ const renderers = [createTableRenderer(), createTimelineRenderer()];
239
+ ```
240
+
241
+ | Binding | Required | Meaning |
242
+ | ---------------------- | -------- | --------------------------------------------------------------------------------------------------- |
243
+ | `?timelineLabel` | Yes | Nonempty plain-text event label. |
244
+ | `?timelineStart` | Yes | Literal ISO year, year-month, calendar date, or timezone-qualified dateTime. |
245
+ | `?timelineEnd` | No | Same format; makes a range. Must not precede the start. |
246
+ | `?timelineGroup` | No | Row/group name. Mixed grouped/ungrouped events use an Other row. |
247
+ | `?timelineLink` | No | Absolute HTTP(S) URL on the label, opened with `noopener noreferrer`. |
248
+ | `?timelineDescription` | No | Plain-text details shown on selection. |
249
+ | `?timelineImage` | No | Absolute HTTP(S) image URI or URL literal. Thumbnail on the timeline and larger image on selection. |
250
+
251
+ Use `# view=timeline; timeline-title=My timeline`. `buildTimelineModel` and
252
+ `parseTimelineDate` are exported for hosts that need to inspect normalized data.
253
+ Years/months start on January 1/the first of the month, at midnight UTC. Full
254
+ calendar dates and dateTimes are validated (including leap days); ambiguous locale
255
+ formats and reversed ranges report their row. Signed extended years and Wikidata's
256
+ leading plus are accepted. No imprecise year/month value is silently treated as an
257
+ exact source date: the display uses the first day of the given period. The example
258
+ uses available Wikidata date literals; date precision/uncertainty qualifiers are
259
+ not modeled. The fallback Timeline data table formats dates in UTC and remains
260
+ available during loading or failure. All labels/descriptions/group names use DOM
261
+ text; query values are never executable HTML.
262
+
263
+ Timeline images load lazily, use no-referrer, and disappear on image errors. Unsafe or invalid image URLs are omitted without dropping events. The example samples one portrait per painter and requests a Commons thumbnail.
264
+
265
+ Options: `libraryUrl` defaults to
266
+ `https://cdn.jsdelivr.net/npm/vis-timeline@8.5.6/standalone/esm/vis-timeline-graph2d.min.mjs`;
267
+ `stylesheetUrl` defaults to the same version's `styles/vis-timeline-graph2d.min.css`
268
+ (or `false` for host-supplied CSS). `loadLibrary` overrides the JS loader and must
269
+ export `Timeline` following `TimelineConstructor`/`TimelineHandle`. Library and CSS
270
+ failures can be retried, stale loads are discarded, and cleanup destroys the view.
271
+ vis-timeline is dual Apache-2.0/MIT licensed. Standalone builds own their internal
272
+ DataSets: these plugins pass plain arrays and do not exchange DataSet instances.
273
+
274
+ ### Lives of Dutch painters example
275
+
276
+ Public endpoint: `https://query.wikidata.org/sparql` (GET). Up to 35 deceased
277
+ painters with a Wikidata image and at least 30 sitelinks, ranked by sitelinks, with birth/death ranges
278
+ and links. MIN/MAX collapse repeated birth/death statements per person; this is a
279
+ data demonstration, not an assessment of conflicting historical dates. Citizenship
280
+ includes the Netherlands and Kingdom of the Netherlands. Names/descriptions prefer
281
+ Dutch and fall back to English.
282
+
283
+ ```sparql
284
+ # view=timeline; timeline-title=Levens van Nederlandse schilders
285
+ PREFIX wd: <http://www.wikidata.org/entity/>
286
+ PREFIX wdt: <http://www.wikidata.org/prop/direct/>
287
+ PREFIX wikibase: <http://wikiba.se/ontology#>
288
+ PREFIX bd: <http://www.bigdata.com/rdf#>
289
+ PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
290
+ PREFIX schema: <http://schema.org/>
291
+
292
+ SELECT ?timelineLabel ?timelineStart ?timelineEnd ?timelineGroup ?timelineDescription ?timelineImage (?person AS ?timelineLink) WHERE {
293
+ {
294
+ SELECT ?person (MIN(?birth) AS ?timelineStart) (MAX(?death) AS ?timelineEnd) (SAMPLE(?portrait) AS ?photo) WHERE {
295
+ VALUES ?country { wd:Q55 wd:Q29999 }
296
+ ?person wdt:P31 wd:Q5 ;
297
+ wdt:P27 ?country ;
298
+ wdt:P106 wd:Q1028181 ;
299
+ wdt:P569 ?birth ;
300
+ wdt:P570 ?death ;
301
+ wdt:P18 ?portrait ;
302
+ wikibase:sitelinks ?sitelinks .
303
+ FILTER(?sitelinks >= 30)
304
+ }
305
+ GROUP BY ?person
306
+ ORDER BY DESC(MAX(?sitelinks))
307
+ LIMIT 35
308
+ }
309
+ BIND(IRI(CONCAT(REPLACE(STR(?photo), "^http:", "https:"), "?width=320")) AS ?timelineImage)
310
+ BIND("Schilders" AS ?timelineGroup)
311
+ SERVICE wikibase:label {
312
+ bd:serviceParam wikibase:language "nl,en" .
313
+ ?person rdfs:label ?timelineLabel ;
314
+ schema:description ?timelineDescription .
315
+ }
316
+ }
317
+ ORDER BY ?timelineStart
318
+ ```
319
+
320
+ ## Pivot
321
+
322
+ **Package:** `@ldforge/pivot` (optional) · **Factory:** `createPivotRenderer(options?)` · **ID:** `pivot`
323
+
324
+ An accessible native HTML pivot table: rows cross columns, cells aggregate the
325
+ matching source observations, and margins show row, column and grand totals. No
326
+ external JavaScript, stylesheet, canvas or runtime dependency is needed.
327
+
328
+ ```ts
329
+ import { createPivotRenderer } from '@ldforge/pivot';
330
+ const renderers = [
331
+ createTableRenderer(),
332
+ createPivotRenderer({ aggregate: 'sum' }),
333
+ ];
334
+ ```
335
+
336
+ | Binding | Required | Meaning |
337
+ | -------------- | -------- | ------------------------------------------------------------- |
338
+ | `?pivotRow` | Yes | Nonempty row category; compared by its exact string value. |
339
+ | `?pivotColumn` | Yes | Nonempty column category; compared by its exact string value. |
340
+ | `?pivotValue` | Yes | Finite numeric literal, including negative values and zero. |
341
+
342
+ Use `# view=pivot; pivot-aggregate=sum; pivot-title=My pivot`. Optional
343
+ `pivot-row-title` and `pivot-column-title` name the axes. Supported aggregations:
344
+
345
+ - `sum` (default): sum of source values.
346
+ - `count`: number of source observations, including zero-valued observations.
347
+ - `avg`: mean of source values. Totals use all underlying observations, so an
348
+ average of displayed averages is never substituted for the weighted mean.
349
+ - `min` and `max`: extrema of source values, including for totals.
350
+
351
+ Repeated row/column pairs are aggregated. Missing combinations display an em dash
352
+ with a “No observations” tooltip, distinct from a real zero. Invalid bindings,
353
+ unsupported operations and nonfinite sum/average results report an error with the
354
+ source row. Numeric cells expose full precision in `title`/`data-value`; localized
355
+ formatting controls the visible representation. Category labels are DOM text,
356
+ never HTML. Group keys such as `__proto__` remain ordinary data.
357
+
358
+ Controls choose the aggregation, sort either axis by labels or totals, swap axes
359
+ without losing observations, and toggle cell colors. Color intensity reflects
360
+ absolute cell magnitude; positive values are green and negative values are warm
361
+ red. Values remain readable independently of color. Row/column headers use table
362
+ scopes; the overflow region is labeled, keyboard-focusable and scrolls horizontally
363
+ on narrow screens. Cleanup disables renderer-owned controls.
364
+
365
+ `PivotRendererOptions` accepts `aggregate`, `heatmap` (default `true`),
366
+ `maximumFractionDigits` (integer 0–20, default 3), `rowTitle` and `columnTitle`.
367
+ Query directives override the initial operation/axis titles; runtime controls only
368
+ change this result view. `buildPivotModel`, `transposePivotModel`, `pivotAggregates`,
369
+ `PivotDataError`, `PivotAggregate` and `PivotModel` are exported for host use.
370
+
371
+ ### Art movements by collection example
372
+
373
+ Public endpoint: `https://query.wikidata.org/sparql` (GET). Counts Wikidata paintings
374
+ by art movement in the Rijksmuseum, Van Gogh Museum and Mauritshuis. Dutch labels
375
+ fall back to English. There is no LIMIT on the grouped combinations, so the pivot
376
+ covers all matches in these three collections. It describes Wikidata coverage,
377
+ not the institutions' complete inventories. A painting can have multiple movement
378
+ or collection statements: totals count assignments across cells, not globally
379
+ unique paintings. Keep the initial `sum` to sum the query's painting counts;
380
+ choosing `count` instead counts the returned grouped query rows.
381
+
382
+ ```sparql
383
+ # view=pivot; pivot-title=Schilderijen per kunststroming en collectie; pivot-aggregate=sum; pivot-row-title=Kunststroming; pivot-column-title=Collectie
384
+ PREFIX wd: <http://www.wikidata.org/entity/>
385
+ PREFIX wdt: <http://www.wikidata.org/prop/direct/>
386
+ PREFIX wikibase: <http://wikiba.se/ontology#>
387
+ PREFIX bd: <http://www.bigdata.com/rdf#>
388
+ PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
389
+
390
+ SELECT ?pivotRow ?pivotColumn ?pivotValue WHERE {
391
+ {
392
+ SELECT ?movement ?collection (COUNT(DISTINCT ?painting) AS ?pivotValue) WHERE {
393
+ # Rijksmuseum, Van Gogh Museum, Mauritshuis
394
+ VALUES ?collection { wd:Q190804 wd:Q224124 wd:Q221092 }
395
+ ?painting wdt:P31 wd:Q3305213 ;
396
+ wdt:P135 ?movement ;
397
+ wdt:P195 ?collection .
398
+ }
399
+ GROUP BY ?movement ?collection
400
+ }
401
+ SERVICE wikibase:label {
402
+ bd:serviceParam wikibase:language "nl,en" .
403
+ ?movement rdfs:label ?pivotRow .
404
+ ?collection rdfs:label ?pivotColumn .
405
+ }
406
+ }
407
+ ORDER BY ?pivotRow ?pivotColumn
408
+ ```
409
+
77
410
  ## Charts
78
411
 
79
412
  **Package:** `@ldforge/charts` (optional, separate from `@ldforge/renderers`) · **Factory:** `createChartRenderer(options?)` · **ID:** `charts`
@@ -219,8 +552,58 @@ const unstyledByQuery = createCardsRenderer({ allowQueryStyles: false });
219
552
 
220
553
  `CardsRendererOptions.allowQueryStyles?: boolean` defaults to `true`. The shared editor stylesheet provides the grid, images, headings and buttons. A standalone renderer can use the same stylesheet or host CSS targeting `.ldforge-cards`, `.ldforge-card`, `.ldforge-card-body` and `.ldforge-card-button`.
221
554
 
555
+ ## Plugin wizard
556
+
557
+ The right-hand toolbar's **Plugin wizard** button guides you through choosing a
558
+ registered renderer, setting its header options, and reviewing a header with
559
+ optional binding-contract comments. **Apply to query** replaces existing renderer
560
+ header settings and previously generated contracts without changing the query
561
+ body, unrelated comments, host metadata or CSS. It does not run or rewrite your
562
+ SELECT/ASK/graph query: use the contract comments to choose matching bindings.
563
+ Closing the dialog leaves the query unchanged.
564
+
565
+ Every registered plugin can appear; only its declared `wizard` metadata supplies
566
+ options and contracts. No unregistered renderer catalogue is imported, and lazy
567
+ visualization libraries are not downloaded. Custom renderers without metadata
568
+ still get a view-only header. For example:
569
+
570
+ ```sparql
571
+ # view=charts; chart=bar; chart-title="My chart"
572
+ # ldforge-bindings:start
573
+ # Pie and doughnut require one nonnegative series.
574
+ # ?chart_label (required): Category label
575
+ # ?chart_value (required): Finite numeric value
576
+ # ?chart_series (optional): Series name
577
+ # ldforge-bindings:end
578
+ ```
579
+
580
+ The button defaults to enabled. Hide it with `controls.rendererWizard: false`, or
581
+ call `editor.getRendererWizard().setVisible(false)` at runtime. The API remains
582
+ available when hidden; `generate(config)` returns a header and `apply(config)`
583
+ applies it to the active query. `editor.getRenderers()` lists registered plugins.
584
+ See [Plugin wizard API](api/editor.md#plugin-wizard) and
585
+ [renderer metadata](api/plugins.md#wizard-metadata) for types and examples.
586
+
222
587
  ## Query headers
223
588
 
589
+ ### Shared endpoints
590
+
591
+ In the demo, a leading endpoint comment makes a query portable:
592
+
593
+ ```sparql
594
+ # view=table
595
+ # sparql-endpoint=https://datasetregister.netwerkdigitaalerfgoed.nl/sparql
596
+ DESCRIBE <https://n2t.net/ark:/72166/dataset>
597
+ ```
598
+
599
+ The endpoint is selected when you run the query and is shown under the editor.
600
+ The request uses fresh connection headers. Live examples include this comment
601
+ when loaded; SELECT, CONSTRUCT, ASK and DESCRIBE basics explicitly select local
602
+ fixtures and make no endpoint request unless you add an endpoint header yourself.
603
+ The Plugin wizard preserves endpoint comments. Embedded applications can enable
604
+ this through core's `createQueryEndpointExecutor`; see
605
+ [portable endpoint headers](api/transport.md#portable-endpoint-headers).
606
+
224
607
  Put metadata in the leading SPARQL comment block, before PREFIX/BASE and the query operation. Keep plugin settings together on one comment line, using semicolon-separated `key=value` assignments: `# view=charts; chart=bar; chart-title=Example city populations`. Put CSS on its own `# css=...` line, because CSS declarations themselves contain semicolons. Separate configuration lines remain supported for existing queries. Blank lines and ordinary comments are allowed in that block. Keys are case-insensitive, values can optionally be quoted, and the last occurrence wins, including across lines. Quote values containing semicolons, for example `chart-title="Cities; populations"`; quoted values also support escaped quotes and backslashes. Apostrophes inside unquoted values such as `People's cities` do not start a quoted value. CSS consumes its entire dedicated comment line; `css` embedded among plugin assignments is ignored. Parsing stops at the first non-comment SPARQL line: comments inside the query and strings are never directives. Formatting and prefix insertion preserve the header. These are normal SPARQL comments and are sent to the executor unchanged.
225
608
 
226
609
  ```sparql
@@ -251,18 +634,41 @@ A custom renderer can read `context?.directives?.['my-setting']`. Document each
251
634
 
252
635
  ## Table
253
636
 
254
- **Package:** `@ldforge/renderers` · **Factory:** `createTableRenderer()` · **ID:** `table`
637
+ **Package:** `@ldforge/renderers` · **Factory:** `createTableRenderer(options?)` · **ID:** `table`
255
638
 
256
- Displays SELECT bindings or CONSTRUCT/DESCRIBE triples as a table. Graph results use subject/predicate/object columns. Column order follows the SELECT variable order, rows follow the endpoint's result order, and unbound values produce empty cells. RDF values are rendered as text, including URL-like values. Datatype and language information appear in cell tooltips. The table caption and result count follow the editor language.
639
+ Displays SELECT bindings or CONSTRUCT/DESCRIBE triples as a table. Graph results use subject/predicate/object columns. Column order follows the SELECT variable order, rows follow the endpoint's result order, and unbound values produce empty cells. RDF values are rendered safely as text. URI terms retain plain text with a small circular information button that opens the resource inspector. Datatype and language information appear in cell tooltips. The table caption and result count follow the editor language.
257
640
 
258
641
  **Binding contract:** supports `kind: 'bindings'` and `kind: 'graph'`. No special variable names are required: `?resource`, `?label`, `?price` or any other SELECT variables become columns. SELECT aliases determine the displayed column names.
259
642
 
643
+ The first plugin example in the demo’s Examples menu (after the four standard queries), **Dataset publishers (table)**,
644
+ uses the NDE Dataset Register endpoint to list publishers and their dataset counts:
645
+
260
646
  ```sparql
261
- SELECT ?resource ?label WHERE {
262
- ?resource <http://www.w3.org/2000/01/rdf-schema#label> ?label .
263
- FILTER (lang(?label) = "en")
647
+ # view=table
648
+ # sparql-endpoint=https://datasetregister.netwerkdigitaalerfgoed.nl/sparql
649
+ PREFIX dcat: <http://www.w3.org/ns/dcat#>
650
+ PREFIX dct: <http://purl.org/dc/terms/>
651
+ PREFIX foaf: <http://xmlns.com/foaf/0.1/>
652
+ PREFIX schema: <https://schema.org/>
653
+
654
+ select ?publisher
655
+ (sample(?pn) as ?publisherName)
656
+ (sample(?dataset) as ?exampleDataset)
657
+ (sample(?t) as ?exampleTitle)
658
+ (count(distinct ?dataset) as ?datasetCount)
659
+ where {
660
+ ?dataset a dcat:Dataset ;
661
+ schema:subjectOf ?registration ;
662
+ dct:title ?t ;
663
+ dct:publisher ?publisher .
664
+
665
+ ?registration schema:additionalType <https://data.netwerkdigitaalerfgoed.nl/registry/valid> .
666
+
667
+ ?publisher foaf:name ?pn .
264
668
  }
265
- LIMIT 20
669
+ group by ?publisher
670
+ order by desc(?datasetCount)
671
+ limit 100
266
672
  ```
267
673
 
268
674
  ```ts
@@ -271,6 +677,96 @@ const renderers = [createTableRenderer()];
271
677
  // Pass renderers to createEditor().
272
678
  ```
273
679
 
680
+ ### Sorting, filters and large results
681
+
682
+ Click a column heading to sort ascending, then descending. Sorting uses a locale-aware
683
+ numeric text comparison (not RDF datatype arithmetic); the original result is never
684
+ mutated. Search all columns or combine case-insensitive per-column substring filters.
685
+ The caption reports the filtered and original counts. These operations use only the
686
+ loaded result; they do not fetch additional endpoint pages or alter CSV downloads.
687
+
688
+ Above 500 rows, the table uses a scroll viewport with a bounded number of rendered
689
+ rows and spacer rows. Rows have a fixed height; long values are truncated visually.
690
+ Small results retain wrapping. Configure `virtualizeThreshold` and `viewportHeight`
691
+ (default 480 pixels) in `TableRendererOptions`. Every loaded row remains searchable
692
+ and sortable, but only visible rows are present in the accessibility tree. For a full
693
+ text value, open a URI in the inspector or use JSON/CSV. All bindings stay in memory;
694
+ endpoint-side LIMIT remains useful for very large queries.
695
+
696
+ ### Resource inspector
697
+
698
+ The information buttons beside URIs open an inline panel with outgoing properties and incoming references.
699
+ Click related URIs to continue exploring; Close or Escape returns focus to the
700
+ original table button. Graph results use matching local triples first. SELECT
701
+ results require a host loader for additional properties; without one the panel
702
+ shows the URI and an empty-data message. HTTP(S) resources also have an explicit
703
+ external link. Resource IRIs are never automatically fetched as web pages.
704
+
705
+ ```ts
706
+ import { createTableRenderer, createResourceLoader } from '@ldforge/renderers';
707
+ createTableRenderer({ loadResource: createResourceLoader(executor) });
708
+ ```
709
+
710
+ `createResourceLoader(executor)` uses the host's query executor with a cancellable
711
+ CONSTRUCT query for outgoing and incoming triples, limited to 200 triples. It rejects
712
+ IRIs containing SPARQL delimiters. The host retains endpoint/authentication policy.
713
+ The demo connects this loader to its active connection. In fixture mode the returned
714
+ graph is demonstration data, not an actual endpoint lookup.
715
+
716
+ For other views, `createResourceInspector(container, { locale, graph?, loadResource? })`
717
+ returns `{ element, open(term), close(), destroy() }`. Append `element` to the host,
718
+ call `open` with a URI term, and call `destroy` during cleanup. A custom
719
+ `ResourceLoader` receives `(iri, signal)` and returns a `Promise<QueryResult>` with
720
+ a graph. Errors appear in the panel; closing, navigating and cleanup abort stale
721
+ requests and prevent late responses from changing the panel.
722
+
723
+ ### Column widths
724
+
725
+ By default, every result column gets `100 / n` percent of the table width. Fixed
726
+ table layout and wrapping prevent a long RDF literal or URI from squeezing the
727
+ other columns. This also applies to the subject/predicate/object columns of
728
+ CONSTRUCT and DESCRIBE results.
729
+
730
+ ```sparql
731
+ # view=table; columns=40%,40%,20%
732
+ DESCRIBE <https://n2t.net/ark:/72166/dataset>
733
+ ```
734
+
735
+ `columns` is the canonical directive; `colums` is accepted as a legacy spelling.
736
+ Supply exactly one positive percentage per result column, totaling 100. Invalid
737
+ or mismatched query widths show a localized warning and use equal widths while
738
+ retaining the result data. If both spellings occur, `columns` takes precedence.
739
+ The Plugin wizard offers this field and reads either spelling from existing
740
+ queries; applying its header writes the canonical `columns` key.
741
+
742
+ ```ts
743
+ createTableRenderer({ columnWidths: [40, 40, 20] });
744
+ ```
745
+
746
+ `TableRendererOptions.columnWidths` supplies default percentages in result-variable
747
+ order. Invalid host percentages throw at construction; a column-count mismatch
748
+ falls back to equal widths at render time with a warning. Query widths override
749
+ host defaults. No arbitrary CSS values are accepted as widths.
750
+
751
+ ### Local DESCRIBE example
752
+
753
+ The demo's **DESCRIBE-voorbeeld** explicitly selects local example data (no
754
+ endpoint) and loads:
755
+
756
+ ```sparql
757
+ DESCRIBE <https://n2t.net/ark:/72166/dataset>
758
+ ```
759
+
760
+ The URI is used as the subject of a small, clearly labeled local demonstration
761
+ graph. These are fixture triples, not a fetched description of the actual dataset.
762
+ The same query can be run manually against
763
+ `https://datasetregister.netwerkdigitaalerfgoed.nl/sparql` for live data. All four
764
+ basic examples (SELECT, CONSTRUCT, ASK, DESCRIBE) reset the active connection to
765
+ local fixtures, even after a live example or manually configured endpoint. The
766
+ demo fixture is deterministic and is not a general SPARQL engine. Every example
767
+ explicitly declares either its endpoint or no endpoint; visual plugin examples
768
+ continue to select their own public service.
769
+
274
770
  ## Boolean
275
771
 
276
772
  **Package:** `@ldforge/renderers` · **Factory:** `createBooleanRenderer()` · **ID:** `boolean`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ldforge/editor",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "LDForge editor: composable SPARQL tooling",
5
5
  "type": "module",
6
6
  "license": "EUPL-1.2",
@@ -35,8 +35,8 @@
35
35
  "@codemirror/lint": "^6.9.8",
36
36
  "@codemirror/state": "^6.7.6",
37
37
  "@codemirror/view": "^6.43.15",
38
- "@ldforge/core": "^0.1.4",
39
- "@ldforge/prefixes": "^0.1.4",
38
+ "@ldforge/core": "^0.1.6",
39
+ "@ldforge/prefixes": "^0.1.6",
40
40
  "@lezer/common": "^1.5.5",
41
41
  "codemirror-lang-sparql": "^2.1.0",
42
42
  "sparql-formatter": "^1.0.2"
package/src/controls.ts CHANGED
@@ -7,8 +7,11 @@ export interface EditorControls {
7
7
  readonly prefixes?: boolean;
8
8
  readonly prefixFolding?: boolean;
9
9
  readonly format?: boolean;
10
+ readonly rendererWizard?: boolean;
11
+ readonly loadingIndicator?: boolean;
10
12
  readonly settings?: boolean;
11
13
  readonly language?: boolean;
14
+ readonly fontSize?: boolean;
12
15
  readonly tabs?: boolean;
13
16
  readonly addTab?: boolean;
14
17
  readonly renameTab?: boolean;
@@ -25,8 +28,11 @@ export function resolveControls(
25
28
  prefixes: true,
26
29
  prefixFolding: true,
27
30
  format: true,
31
+ rendererWizard: true,
32
+ loadingIndicator: true,
28
33
  settings: true,
29
34
  language: true,
35
+ fontSize: true,
30
36
  tabs: true,
31
37
  addTab: true,
32
38
  renameTab: true,