@ldforge/editor 0.1.5 → 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.
package/docs/renderers.md CHANGED
@@ -46,7 +46,7 @@ Positive polygon heights default to **3D**, unless `mode`/`geo-mode` or the host
46
46
  loaded from a pinned external module with matching CSS only when needed. Normal,
47
47
  Grouped and Heatmap continue to use Leaflet without downloading MapLibre.
48
48
 
49
- The demo's **Paleis het Loo (3D)** example uses the OSM endpoint below:
49
+ The demo's **Paleis het Loo (Geo 3D)** example uses the OSM endpoint below:
50
50
 
51
51
  ```sparql
52
52
  # view=geo; mode=3d; geo-title=Paleis het Loo
@@ -75,9 +75,10 @@ Normal. Text geometry/height data stays available. Self-host using
75
75
 
76
76
  ### Castles in North Holland example
77
77
 
78
- Endpoint: `https://query.wikidata.org/sparql` (GET). The demo's **Kastelen in Noord-Holland**
78
+ Endpoint: `https://query.wikidata.org/sparql` (GET). The demo's **Kastelen in Nederland (Geo)**
79
79
  returns up to 250 castles in North Holland with coordinates and a Wikidata image. It uses
80
- mandatory patterns without OPTIONAL. Popup labels link to Wikidata; descriptions
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
81
82
  prefer Dutch and fall back to English. Commons images use HTTPS thumbnail URLs.
82
83
  The missing `rdfs` and `schema` prefixes are included explicitly.
83
84
 
@@ -90,13 +91,16 @@ PREFIX bd: <http://www.bigdata.com/rdf#>
90
91
  PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
91
92
  PREFIX schema: <http://schema.org/>
92
93
 
93
- SELECT ?place ?geometryLabel ?geoDescription ?geoImage ?geometry (?place AS ?geoLink) WHERE {
94
+ SELECT ?place ?geometryLabel ?geoDescription ?geoImage ?geometry ?geoLink WHERE {
94
95
  ?place wdt:P31 wd:Q23413 ;
95
96
  wdt:P17 wd:Q55 ;
96
97
  wdt:P131+ wd:Q701 ;
97
98
  wdt:P625 ?geometry ;
98
99
  wdt:P18 ?image .
99
100
 
101
+ ?geoLink schema:about ?place ;
102
+ schema:isPartOf <https://nl.wikipedia.org/> .
103
+
100
104
  SERVICE wikibase:label {
101
105
  bd:serviceParam wikibase:language "nl,en" .
102
106
  ?place rdfs:label ?geometryLabel ;
@@ -108,8 +112,14 @@ SELECT ?place ?geometryLabel ?geoDescription ?geoImage ?geometry (?place AS ?geo
108
112
  LIMIT 250
109
113
  ```
110
114
 
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
+
111
121
  Wikidata's `wdt:P625` returns WGS84 WKT points directly, so no geometry conversion
112
- is needed. The separate **Paleis het Loo (3D)** example above keeps using OSM.
122
+ is needed. The separate **Paleis het Loo (Geo 3D)** example above keeps using OSM.
113
123
 
114
124
  This deterministic query demonstrates all three basic types on any SPARQL 1.1 endpoint:
115
125
 
@@ -130,6 +140,273 @@ See [GeoRendererOptions and supported WKT](https://github.com/mightymax/ldforge/
130
140
 
131
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.
132
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
+
133
410
  ## Charts
134
411
 
135
412
  **Package:** `@ldforge/charts` (optional, separate from `@ldforge/renderers`) · **Factory:** `createChartRenderer(options?)` · **ID:** `charts`
@@ -275,8 +552,58 @@ const unstyledByQuery = createCardsRenderer({ allowQueryStyles: false });
275
552
 
276
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`.
277
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
+
278
587
  ## Query headers
279
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
+
280
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.
281
608
 
282
609
  ```sparql
@@ -307,18 +634,41 @@ A custom renderer can read `context?.directives?.['my-setting']`. Document each
307
634
 
308
635
  ## Table
309
636
 
310
- **Package:** `@ldforge/renderers` · **Factory:** `createTableRenderer()` · **ID:** `table`
637
+ **Package:** `@ldforge/renderers` · **Factory:** `createTableRenderer(options?)` · **ID:** `table`
311
638
 
312
- 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.
313
640
 
314
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.
315
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
+
316
646
  ```sparql
317
- SELECT ?resource ?label WHERE {
318
- ?resource <http://www.w3.org/2000/01/rdf-schema#label> ?label .
319
- 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 .
320
668
  }
321
- LIMIT 20
669
+ group by ?publisher
670
+ order by desc(?datasetCount)
671
+ limit 100
322
672
  ```
323
673
 
324
674
  ```ts
@@ -327,6 +677,96 @@ const renderers = [createTableRenderer()];
327
677
  // Pass renderers to createEditor().
328
678
  ```
329
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
+
330
770
  ## Boolean
331
771
 
332
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.5",
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.5",
39
- "@ldforge/prefixes": "^0.1.5",
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,
@@ -0,0 +1,57 @@
1
+ import type { Locale } from '@ldforge/core';
2
+ export const DEFAULT_FONT_SIZE = 12;
3
+ export function validateFontSize(value: number): void {
4
+ if (!Number.isInteger(value) || value < 10 || value > 24)
5
+ throw new RangeError('fontSize must be an integer from 10 to 24.');
6
+ }
7
+ export function createFontSizeControl(
8
+ doc: Document,
9
+ current: () => number,
10
+ locale: () => Locale,
11
+ onChange: (size: number) => void,
12
+ ) {
13
+ const element = doc.createElement('fieldset');
14
+ element.className = 'ldforge-font-size';
15
+ const legend = doc.createElement('legend');
16
+ const smaller = doc.createElement('button');
17
+ smaller.type = 'button';
18
+ smaller.textContent = 'A−';
19
+ const larger = doc.createElement('button');
20
+ larger.type = 'button';
21
+ larger.textContent = 'A+';
22
+ const reset = doc.createElement('button');
23
+ reset.type = 'button';
24
+ const select = doc.createElement('select');
25
+ for (let size = 10; size <= 24; size++)
26
+ select.append(new Option(`${size} px`, String(size)));
27
+ element.append(legend, smaller, select, larger, reset);
28
+ smaller.addEventListener('click', () =>
29
+ onChange(Math.max(10, current() - 1)),
30
+ );
31
+ larger.addEventListener('click', () => onChange(Math.min(24, current() + 1)));
32
+ reset.addEventListener('click', () => onChange(DEFAULT_FONT_SIZE));
33
+ select.addEventListener('change', () => onChange(Number(select.value)));
34
+ function refresh() {
35
+ const nl = locale() === 'nl';
36
+ legend.textContent = nl ? 'Tekstgrootte' : 'Text size';
37
+ select.setAttribute('aria-label', legend.textContent);
38
+ select.value = String(current());
39
+ smaller.setAttribute(
40
+ 'aria-label',
41
+ nl ? 'Tekst verkleinen' : 'Decrease text size',
42
+ );
43
+ larger.setAttribute(
44
+ 'aria-label',
45
+ nl ? 'Tekst vergroten' : 'Increase text size',
46
+ );
47
+ reset.textContent = nl ? 'Herstellen' : 'Reset';
48
+ reset.setAttribute(
49
+ 'aria-label',
50
+ nl ? 'Tekstgrootte herstellen' : 'Reset text size',
51
+ );
52
+ smaller.disabled = current() === 10;
53
+ larger.disabled = current() === 24;
54
+ }
55
+ refresh();
56
+ return { element, refresh };
57
+ }