@ldforge/editor 0.1.6 → 0.1.7

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 +105 -0
  2. package/package.json +3 -3
package/docs/renderers.md CHANGED
@@ -851,3 +851,108 @@ When adding a plugin that interprets particular variables, its documentation mus
851
851
  - Any external services, resources or host configuration needed for rendering.
852
852
 
853
853
  Explain validation failures in the renderer rather than silently guessing a different binding. Link the plugin to the relevant section with `documentationUrl`. See the [Plugin API](api/plugins.md) for icon factories, cleanup and rendering contracts, or the [Integration guide](../apps/demo/guide.html) for embedding examples.
854
+
855
+ ## Tree
856
+
857
+ Register `createTreeRenderer()` from the optional `@ldforge/tree` package in `renderers`. No visualization dependency is required. See the [package README](https://github.com/mightymax/ldforge/tree/main/packages/tree#readme) for installation and host integration.
858
+
859
+ ### Binding contract
860
+
861
+ SELECT results must declare `tree_id`; rows without a valid ID are skipped and counted in the diagnostic. No parent or label columns are required.
862
+
863
+ | Binding | Meaning |
864
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
865
+ | `tree_id` | Required nonempty URI or stable literal identifier. Blank nodes and whitespace-only values are rejected. |
866
+ | `tree_parent` | Optional identifier using exactly the same matching rules. An unbound/invalid parent makes the row a root candidate. Invalid bound parents are counted. |
867
+ | `tree_label` | Optional nonempty term value displayed as text; defaults to the original identifier value. |
868
+ | `tree_url` | Optional absolute HTTP(S) term value; all other schemes and relative URLs are ignored. No automatic dereferencing. |
869
+
870
+ Matching is exact and case-sensitive on lexical values, with URI and literal identities kept separate. No trimming, URL normalization, prefix expansion or numeric coercion is applied to IDs. Literal identity includes datatype and lowercased language tag. Plain literals and `xsd:string` match; `literal` and legacy `typed-literal` with the same datatype match. Language literals default to `rdf:langString`. The original ID term is preserved independently of the label and URL; for equivalent term encodings the first original term is retained.
871
+
872
+ Repeated IDs merge; repeated parent/child edges merge. Conflicting nonempty labels and valid URLs use the lexicographically smallest value (UTF-16 order), independent of result row order. Sorting uses the serialized identity key, not the label or browser locale. Missing parents are omitted, counted once per missing identifier, and their children become root candidates unless they also have a present parent.
873
+
874
+ ### Shared children, cycles and large results
875
+
876
+ A deterministic iterative depth-first spanning forest assigns each resource one expandable occurrence. Start with sorted root candidates, then start any still-unvisited components at their smallest remaining key. A candidate already reached from another root stays there. Other incoming edges appear as terminal **(reference)** occurrences with the same original ID, link and inspector action. This avoids exponentially repeated subtrees. References do not expand or jump to another occurrence.
877
+
878
+ Back edges are counted under **Cycles** and rendered as references. This count is a diagnostic, not the number of all mathematical cycles. Cyclic-only datasets therefore remain visible, including self loops; no traversal or rendering uses recursive calls.
879
+
880
+ All branches start collapsed. Expanding creates only the visible rows; collapsing removes descendants. Rendering is O(visible nodes + visible edges), and the model is O(nodes + edges) after key sorting. This is lazy branch rendering, not viewport virtualization: a very wide expanded branch still creates every immediate child. Input results remain in memory. Indentation is capped visually after 30 levels while ARIA levels retain full depth.
881
+
882
+ ### Options, accessibility and lifecycle
883
+
884
+ `createTreeRenderer({ title?, onInspect? })` accepts a default title and a host callback `(term: BindingTerm) => void`. `# view=tree` selects the registered renderer; `# tree-title=...` overrides its title. The wizard includes all four bindings and the title option. UI labels and diagnostics support English and Dutch through the editor locale.
885
+
886
+ A single tree item is in the Tab sequence. Up/Down move through visible items; Home/End select first/last; Right expands or enters a branch; Left collapses or selects the parent; Enter/Space toggle. Pointer clicks select and toggle. The selected resource's link and optional inspector button follow the tree. Flat treeitems expose `aria-level`, `aria-posinset`, `aria-setsize`, `aria-selected` and branch `aria-expanded`.
887
+
888
+ The renderer returns cleanup that removes all its listeners and expansion state. The editor invokes it on result/view changes and destruction. No network requests, timers or global listeners are created.
889
+
890
+ To use the shared resource inspector without embedding endpoint configuration in this package, have the host own its panel and loader:
891
+
892
+ ```ts
893
+ import {
894
+ createResourceInspector,
895
+ createResourceLoader,
896
+ } from '@ldforge/renderers';
897
+ const inspector = createResourceInspector(
898
+ document.querySelector('#inspector')!,
899
+ {
900
+ loadResource: createResourceLoader(executor), // host-owned QueryExecutor
901
+ },
902
+ );
903
+ const tree = createTreeRenderer({
904
+ onInspect: (term) => {
905
+ void inspector.open(term);
906
+ },
907
+ });
908
+ // Register tree in your editor. On host unmount: inspector.destroy(); editor.destroy().
909
+ ```
910
+
911
+ The inspector button appears only for URI IDs when `onInspect` is supplied; it passes `tree_id`, never a label or `tree_url`.
912
+
913
+ ### Runnable local SKOS example
914
+
915
+ Run `npm ci && npm run dev` at the repository root, choose **Examples → SKOS hierarchy (local tree)**, then **Run query**. The fixture is deterministic and requires no endpoint. The same complete query runs against any SPARQL 1.1 endpoint:
916
+
917
+ ```sparql
918
+ # view=tree
919
+ PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
920
+ SELECT ?tree_id ?tree_parent ?tree_label ?tree_url WHERE {
921
+ VALUES (?tree_id ?tree_parent ?tree_label) {
922
+ (<https://example.org/art> UNDEF "Art")
923
+ (<https://example.org/painting> <https://example.org/art> "Painting")
924
+ (<https://example.org/drawing> <https://example.org/art> "Drawing")
925
+ (<https://example.org/watercolor> <https://example.org/painting> "Watercolor")
926
+ (<https://example.org/watercolor> <https://example.org/drawing> "Watercolor")
927
+ }
928
+ BIND(?tree_id AS ?tree_url)
929
+ }
930
+ ```
931
+
932
+ These rows describe `tree_id skos:broader tree_parent`. The fixture deliberately shares Watercolor between Drawing and Painting.
933
+
934
+ ### Optional live SKOS example: Getty AAT
935
+
936
+ Choose **Examples → Getty paintings (live tree)** or run this query with GET at `https://vocab.getty.edu/sparql.json`. It includes the painting root and two narrower levels, retaining shared children. Availability and counts depend on Getty; automated tests never require it.
937
+
938
+ ```sparql
939
+ # view=tree
940
+ # sparql-endpoint=https://vocab.getty.edu/sparql.json
941
+ PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
942
+ PREFIX aat: <http://vocab.getty.edu/aat/>
943
+ SELECT DISTINCT ?tree_id ?tree_parent ?tree_label ?tree_url WHERE {
944
+ VALUES ?root { aat:300033618 }
945
+ { BIND(?root AS ?tree_id) }
946
+ UNION {
947
+ ?tree_parent skos:broader? ?root .
948
+ ?tree_id skos:broader ?tree_parent .
949
+ }
950
+ OPTIONAL {
951
+ ?tree_id skos:prefLabel ?label .
952
+ FILTER(LANGMATCHES(LANG(?label), "en"))
953
+ }
954
+ BIND(COALESCE(?label, STR(?tree_id)) AS ?tree_label)
955
+ BIND(?tree_id AS ?tree_url)
956
+ }
957
+ ORDER BY ?tree_parent ?tree_label ?tree_id
958
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ldforge/editor",
3
- "version": "0.1.6",
3
+ "version": "0.1.7",
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.6",
39
- "@ldforge/prefixes": "^0.1.6",
38
+ "@ldforge/core": "^0.1.7",
39
+ "@ldforge/prefixes": "^0.1.7",
40
40
  "@lezer/common": "^1.5.5",
41
41
  "codemirror-lang-sparql": "^2.1.0",
42
42
  "sparql-formatter": "^1.0.2"