@ldforge/editor 0.1.2 → 0.1.4

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 (2) hide show
  1. package/docs/renderers.md +73 -1
  2. package/package.json +3 -3
package/docs/renderers.md CHANGED
@@ -2,6 +2,78 @@
2
2
 
3
3
  LDForge result renderers turn normalized SELECT, ASK or RDF graph results into independent views. Choose a view through the icon tabs below the query editor. Only plugins supporting the current result appear. The download button always exports the complete result as CSV.
4
4
 
5
+ ## Geo
6
+
7
+ **Package:** `@ldforge/geo` (optional) · **Factory:** `createGeoRenderer(options?)` · **ID:** `geo`
8
+
9
+ Shows WKT points, lines and polygons on an interactive Leaflet map, with automatic bounds and plain-text label popups. The small adapter loads pinned Leaflet 1.9.4 JavaScript and CSS only on activation, outside the application bundle, following the chart plugin's loading pattern. No Leaflet runtime dependency is installed.
10
+
11
+ ```ts
12
+ import { createGeoRenderer } from '@ldforge/geo';
13
+ // Add alongside your other result renderers:
14
+ const renderers = [createTableRenderer(), createGeoRenderer()];
15
+ ```
16
+
17
+ ### Geo binding contract
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. |
23
+
24
+ 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
+
26
+ ### Map display modes
27
+
28
+ The compact button group offers **Normal**, **Grouped**, and **Heatmap** (localized in Dutch). Normal draws each feature. Grouped uses Supercluster to combine nearby points, shows their counts, and expands clusters on click or zoom. Heatmap uses simpleheat to show point density with equal weight per point. MultiPoint members are individual observations. Lines and polygons remain visible in all modes and are not interpreted as point observations. When there are only shapes, the original geometry is shown without loading a mode library.
29
+
30
+ 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
+
32
+ ### OpenStreetMap example
33
+
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.
35
+
36
+ ```sparql
37
+ # view=geo; mode=heatmap; geo-title=Atletiekbanen in Nederland
38
+ PREFIX geo: <http://www.opengis.net/ont/geosparql#>
39
+ PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
40
+ 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>
43
+
44
+ SELECT ?place ?geometryLabel ?geometry WHERE {
45
+ ?place osmt:leisure track: ;
46
+ geo:hasGeometry/geo:asWKT ?geometry .
47
+
48
+ OPTIONAL {
49
+ ?place skos:prefLabel ?name .
50
+ }
51
+
52
+ BIND(COALESCE(?name, "Atletiekbaan") AS ?geometryLabel)
53
+ }
54
+ ```
55
+
56
+ The source supplies geometry through `geo:hasGeometry/geo:asWKT`. Other projections must first be converted to WGS84/CRS84.
57
+
58
+ This deterministic query demonstrates all three basic types on any SPARQL 1.1 endpoint:
59
+
60
+ ```sparql
61
+ # view=geo; geo-title=Points, lines and polygons
62
+ SELECT ?geometryLabel ?geometry WHERE {
63
+ VALUES (?geometryLabel ?geometry) {
64
+ ("Point" "POINT(4.9 52.37)")
65
+ ("Line" "LINESTRING(4.88 52.36,4.92 52.38)")
66
+ ("Area" "POLYGON((4.86 52.35,4.89 52.35,4.89 52.38,4.86 52.35))")
67
+ }
68
+ }
69
+ ```
70
+
71
+ ### Loading, hosting and lifecycle
72
+
73
+ See [GeoRendererOptions and supported WKT](https://github.com/mightymax/ldforge/blob/main/packages/geo/README.md) for every option. Defaults are `https://cdn.jsdelivr.net/npm/leaflet@1.9.4/+esm`, the matching external `dist/leaflet.css`, and OpenStreetMap raster tiles with visible attribution. `libraryUrl`, `stylesheetUrl`, `tileUrl` and `tileAttribution` allow self-hosting/custom providers. `loadLibrary` overrides the JavaScript loader only; set `stylesheetUrl: false` if the host supplies CSS. Set `tileUrl: false` for no basemap requests. The exported `GeoLibrary`, `GeoMapHandle` and `GeoLayerHandle` interfaces avoid a mandatory Leaflet type dependency.
74
+
75
+ 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
+
5
77
  ## Charts
6
78
 
7
79
  **Package:** `@ldforge/charts` (optional, separate from `@ldforge/renderers`) · **Factory:** `createChartRenderer(options?)` · **ID:** `charts`
@@ -120,7 +192,7 @@ Image and button URLs accept HTTP(S) or relative URLs resolved against the host
120
192
 
121
193
  ### Complete Cards query
122
194
 
123
- This query works without a dataset because it uses VALUES. Replace the image and destination URLs with your own. The demo's **Cards example** uses local sample images and a deterministic fixture, so it also works without an endpoint.
195
+ This query works without a dataset because it uses VALUES. Replace the image and destination URLs with your own. The demo's **Plugin Examples → Cards example** instead loads the [Wikidata cat grid](https://ldforge.nl/wikidata-cats.html) query and selects `https://query.wikidata.org/sparql` over GET. Press Run query to fetch twelve cats with pictures, descriptions and links. This live example requires internet access; selecting it updates the endpoint settings and remembered endpoint, and does not reuse authentication headers from another connection. Choose **Local fixture (no endpoint)** in settings to return to offline sample data.
124
196
 
125
197
  ```sparql
126
198
  # view=cards
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ldforge/editor",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
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.2",
39
- "@ldforge/prefixes": "^0.1.2",
38
+ "@ldforge/core": "^0.1.4",
39
+ "@ldforge/prefixes": "^0.1.4",
40
40
  "@lezer/common": "^1.5.5",
41
41
  "codemirror-lang-sparql": "^2.1.0",
42
42
  "sparql-formatter": "^1.0.2"