@ldforge/editor 0.1.8 → 1.0.0

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 (54) hide show
  1. package/README.md +37 -0
  2. package/dist/controls.d.ts +2 -0
  3. package/dist/controls.d.ts.map +1 -1
  4. package/dist/controls.js +2 -0
  5. package/dist/controls.js.map +1 -1
  6. package/dist/editor-height.d.ts +8 -0
  7. package/dist/editor-height.d.ts.map +1 -0
  8. package/dist/editor-height.js +34 -0
  9. package/dist/editor-height.js.map +1 -0
  10. package/dist/index.d.ts +33 -0
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +347 -33
  13. package/dist/index.js.map +1 -1
  14. package/dist/renderer-info.d.ts +4 -0
  15. package/dist/renderer-info.d.ts.map +1 -0
  16. package/dist/renderer-info.js +41 -0
  17. package/dist/renderer-info.js.map +1 -0
  18. package/dist/renderer-wizard.d.ts.map +1 -1
  19. package/dist/renderer-wizard.js +109 -25
  20. package/dist/renderer-wizard.js.map +1 -1
  21. package/dist/share.d.ts +16 -0
  22. package/dist/share.d.ts.map +1 -0
  23. package/dist/share.js +113 -0
  24. package/dist/share.js.map +1 -0
  25. package/dist/sparql/completion.d.ts.map +1 -1
  26. package/dist/sparql/completion.js +5 -0
  27. package/dist/sparql/completion.js.map +1 -1
  28. package/dist/styles.css +496 -82
  29. package/dist/tab-api.d.ts +7 -1
  30. package/dist/tab-api.d.ts.map +1 -1
  31. package/dist/tab-api.js +29 -1
  32. package/dist/tab-api.js.map +1 -1
  33. package/dist/theme.d.ts +4 -0
  34. package/dist/theme.d.ts.map +1 -0
  35. package/dist/theme.js +73 -0
  36. package/dist/theme.js.map +1 -0
  37. package/docs/api/configuration.md +72 -21
  38. package/docs/api/editor.md +184 -19
  39. package/docs/api/overview.md +8 -0
  40. package/docs/api/plugins.md +6 -2
  41. package/docs/api/tab.md +37 -9
  42. package/docs/api/transport.md +19 -2
  43. package/docs/renderers.md +29 -1
  44. package/package.json +3 -3
  45. package/src/controls.ts +4 -0
  46. package/src/editor-height.ts +42 -0
  47. package/src/index.ts +440 -30
  48. package/src/renderer-info.ts +52 -0
  49. package/src/renderer-wizard.ts +114 -25
  50. package/src/share.ts +125 -0
  51. package/src/sparql/completion.ts +5 -0
  52. package/src/styles.css +496 -82
  53. package/src/tab-api.ts +44 -4
  54. package/src/theme.ts +87 -0
@@ -38,6 +38,9 @@ const editor = createEditor(container, {
38
38
  }),
39
39
  query: 'select * where { ?s ?p ?o } limit 10',
40
40
  locale: 'auto',
41
+ themeMainColor: '#1a80b9',
42
+ editorRows: 15,
43
+ autoGrow: false,
41
44
  controls: { prefixes: true, format: true, settings: true, download: true },
42
45
  sparql: { prefixes },
43
46
  renderers: [
@@ -84,6 +87,11 @@ if (first) {
84
87
  first.rename('My first query');
85
88
  first.addPrefix('sdo', 'https://schema.org/');
86
89
  first.addPrefix('dct');
90
+ editor.setThemeMainColor('#1a80b9');
91
+ console.log(editor.getThemeMainColor());
92
+ console.log(editor.getPrefixes(), first.getPrefixes());
93
+ first.removePrefix('dct');
94
+ editor.removePrefix('unused');
87
95
  }
88
96
 
89
97
  const second = tabs.addTab({
@@ -18,7 +18,7 @@ Plugins are trusted host code, registered per editor instance. IDs must be uniqu
18
18
 
19
19
  ## EditorContext
20
20
 
21
- The context passed to actions/settings is the active-query subset of `ForgeEditor`: `getQuery`, `setQuery`, `formatQuery`, `addPrefix`, `getState`, `run`, `cancel`, `getLocale`, and `setLocale`. Toolbar access, tab collections, mounting and destruction are on the host's `ForgeEditor` handle. See [Editor](editor.md) for method semantics. `formatQuery` returns a promise and must be returned or awaited by an action.
21
+ The context passed to actions/settings is the active-query subset of `ForgeEditor`: `getQuery`, `setQuery`, `formatQuery`, `getPrefixes`, `removePrefix`, `addPrefix`, `getState`, `run`, `cancel`, `getLocale`, and `setLocale`. Toolbar access, tab collections, mounting and destruction are on the host's `ForgeEditor` handle. See [Editor](editor.md) for method semantics. `formatQuery` returns a promise and must be returned or awaited by an action.
22
22
 
23
23
  ## ResultRendererPlugin
24
24
 
@@ -30,7 +30,9 @@ The context passed to actions/settings is the active-query subset of `ForgeEdito
30
30
  | `supports(result)` | `boolean` | Whether this renderer can display the result. |
31
31
  | `render(container, result, context?)` | `void \| (() => void)` | Synchronous render. Optional context is `ResultRendererContext` (see below). Return cleanup for listeners or framework roots. |
32
32
 
33
- Only supported renderers appear in the result tabs, in registration order. Tabs retain the selected renderer across successful queries when it still supports the result, otherwise the first supported renderer is selected. Arrow keys wrap between tabs; Home/End select the first/last tab. Only the selected tab is in the normal Tab sequence. Labels remain visible and accessible with or without icons. The previous renderer is cleaned up before another view/state is rendered or the editor is destroyed. Render RDF with `textContent`, not HTML. Renderer-owned asynchronous work must be cancelled in its cleanup function.
33
+ By default, Table and JSON stay on the result bar when registered; the active renderer is also shown. Other registered renderers appear in the Choose view dropdown, disabled when `supports(result)` returns false. Its information buttons display the plugin-owned binding contract even when a view is disabled. Use `visiblePlugins` / `availablePlugins` or the [runtime visibility methods](editor.md#result-plugin-visibility) to change presentation. Visibility does not register plugins, select views or load external visualization libraries.
34
+
35
+ The selected renderer is retained across successful queries when it still supports the result; otherwise the first supported registered renderer is selected. Left/Right and Home/End switch enabled visible tabs, skipping closed dropdown entries. In the dropdown, Up/Down and Home/End move focus among enabled choices and information buttons; Escape closes it. Labels remain accessible with or without icons. If a query header requests a missing or unsupported view, a warning is shown above the results; missing required variable names are taken from the plugin's declared binding contract. The previous renderer is cleaned up before another view/state is rendered or the editor is destroyed. Render RDF with `textContent`, not HTML. Renderer-owned asynchronous work must be cancelled in its cleanup function.
34
36
 
35
37
  Use `documentationUrl` to describe required bindings, accepted term types, configuration and complete example queries. The built-in renderers link to their usage guides on `https://ldforge.nl/plugins.html`; the demo overrides these links to its local Plugins page. Existing plugins without a URL show no documentation control. Set `controls.rendererDocumentation: false` to hide it globally.
36
38
 
@@ -87,6 +89,8 @@ The generic `PluginRegistry<T extends { id: string }>` is exported by core. Cons
87
89
  ## Wizard metadata
88
90
 
89
91
  A result renderer can declare optional `wizard: RendererWizardSchema` metadata.
92
+ The renderer dropdown’s information button shows this description and binding contract, even when the renderer is disabled. The same metadata works for third-party plugins without registration in a built-in catalogue. `supports(result)` remains responsible for applicability; metadata describes requirements but does not replace validation.
93
+
90
94
  It belongs to the plugin: the editor has no global catalogue of unregistered
91
95
  renderers. Schemas are plain data and do not load visualization libraries.
92
96
 
package/docs/api/tab.md CHANGED
@@ -15,15 +15,17 @@ Properties other than `id` require a live editor. `name` throws for a deleted ta
15
15
 
16
16
  ## Methods
17
17
 
18
- | Method | Returns | Behavior |
19
- | ------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
20
- | `getQuery()` | `string` | Reads this tab's source, including inactive tabs. |
21
- | `setQuery(query)` | `void` | Replaces this tab's text. Active edits are undoable and emit both query/workspace callbacks; inactive edits emit only the workspace callback. |
22
- | `formatQuery(options?)` | `Promise<string>` | Formats this tab without activating it. See [formatting behavior](editor.md#formatting-options). |
23
- | `addPrefix(prefix, namespace?)` | `string \| undefined` | Adds a declaration and returns the actual alias. Resolves shorthand through the configured catalog when namespace is omitted. |
24
- | `rename(name)` | `void` | Trims and persists the name. Empty/whitespace restores the automatic label. Names need not be unique. |
25
- | `activate()` | `void` | Makes this tab active. Calling it on the active tab is a no-op. Does not force keyboard focus. |
26
- | `delete()` | `boolean` | Removes this tab; returns false if it is the only remaining tab. |
18
+ | Method | Returns | Behavior |
19
+ | ------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
20
+ | `getQuery()` | `string` | Reads this tab's source, including inactive tabs. |
21
+ | `setQuery(query)` | `void` | Replaces this tab's text. Active edits are undoable and emit both query/workspace callbacks; inactive edits emit only the workspace callback. |
22
+ | `formatQuery(options?)` | `Promise<string>` | Formats this tab without activating it. See [formatting behavior](editor.md#formatting-options). |
23
+ | `getPrefixes()` | `Record<string, string>` | Detached snapshot of explicitly declared aliases and namespaces; excludes the completion catalog. |
24
+ | `removePrefix(prefix)` | `void` | Removes all declarations of this alias. A missing alias is a no-op. |
25
+ | `addPrefix(prefix, namespace?)` | `string \| undefined` | Adds a declaration and returns the actual alias. Resolves shorthand through the configured catalog when namespace is omitted. |
26
+ | `rename(name)` | `void` | Trims and persists the name. Empty/whitespace restores the automatic label. Names need not be unique. |
27
+ | `activate()` | `void` | Makes this tab active. Calling it on the active tab is a no-op. Does not force keyboard focus. |
28
+ | `delete()` | `boolean` | Removes this tab; returns false if it is the only remaining tab. |
27
29
 
28
30
  Methods throw for deleted tabs or a destroyed editor. Formatting additionally rejects for invalid syntax or if this tab's text changes before the async format finishes. It never overwrites newer source. Deleting another tab does not invalidate this handle.
29
31
 
@@ -57,3 +59,29 @@ console.log(tab.getQuery());
57
59
  // The previously active query remains displayed until this call:
58
60
  tab.activate();
59
61
  ```
62
+
63
+ ## Inspecting and removing prefixes
64
+
65
+ Declarations are parsed structurally: PREFIX-like text in comments, literals and
66
+ IRIs is ignored. With duplicate alias declarations, the last declaration wins in
67
+ the snapshot; removal deletes all declarations of that alias. The empty string
68
+ addresses the default prefix. Namespaces are returned as written inside the IRI
69
+ brackets, without resolving BASE or decoding escapes.
70
+
71
+ Removal deletes the whole line, including its line ending, when a declaration
72
+ is alone on that line. On shared lines it removes only the declaration, retaining
73
+ comments and other statements. Existing blank separator lines and the query body
74
+ are preserved. Uses of the removed alias are left intact, so the query may need a
75
+ replacement declaration before execution. Active edits participate in undo/redo
76
+ and emit the normal query/workspace callbacks. Inactive tab edits emit only the
77
+ workspace callback and never select the tab. As with other tab edits, inactive
78
+ tabs store text only; undo history resets on tab switches. Manual edits and tab
79
+ switches invoke the normal callbacks, where hosts can read a fresh snapshot.
80
+
81
+ ```ts
82
+ const tab = editor.getTabs().getActive();
83
+ const declared = tab.getPrefixes();
84
+ if (declared.ex !== undefined) tab.removePrefix('ex');
85
+ else tab.addPrefix('ex', 'https://example.org/');
86
+ console.log(editor.getPrefixes()); // Current active query declarations.
87
+ ```
@@ -34,7 +34,7 @@ type QueryResult =
34
34
 
35
35
  `Binding` maps variable names without sigils to `BindingTerm`. Unbound variables are absent. A term has readonly `type` (uri, bnode, literal or typed-literal), `value: string`, optional `datatype: string`, and optional `'xml:lang': string`.
36
36
 
37
- `@ldforge/renderers` exports `createTableRenderer()`, `createCardsRenderer(options?)`, `createBooleanRenderer()`, and `createJsonRenderer()`. JSON renders the normalized result model, not the endpoint's raw response. Table cells use text, and boolean/table captions follow editor locale.
37
+ `@ldforge/renderers` exports `createTableRenderer()`, `createCardsRenderer(options?)`, `createBooleanRenderer()`, and `createJsonRenderer()`. JSON shows the normalized result model in a read-only CodeMirror editor with syntax highlighting and a copy button with confirmation; it does not show the endpoint's raw response. Table cells use text, and boolean/table captions follow editor locale. Its RDF details toggle adds URI/blank-node notation, literal quoting and themed superscript datatype/language metadata without converting endpoint lexical values. Configure the initial mode with `createTableRenderer({ showRdfDetails: true })`; the default is false. See the [Table guide](../../docs/renderers.md#rdf-details).
38
38
 
39
39
  ## RDF graph execution
40
40
 
@@ -96,7 +96,7 @@ A newer request cancels the previous request. Cancellation and identity checks s
96
96
  ## Portable endpoint headers
97
97
 
98
98
  The demo honors a `sparql-endpoint` directive in the leading query-comment block.
99
- It selects the endpoint on **Run**, updates visible connection settings/history,
99
+ It selects the endpoint on **Run**, updates the active connection and saved endpoint list,
100
100
  and uses GET. Pasting or loading a query alone does not execute a request.
101
101
 
102
102
  ```sparql
@@ -130,3 +130,20 @@ execution. All four basic examples choose local data. Live examples prepend thei
130
130
  own `sparql-endpoint` comment so a copied query carries its connection with it.
131
131
  Adding such a header manually to a basic query opts into that live endpoint.
132
132
  The Plugin wizard preserves this transport directive while updating renderers.
133
+
134
+ ## Demo endpoint manager
135
+
136
+ The demo's gear panel lists saved endpoints with their HTTP method and current
137
+ selection. Add endpoint opens a blank URL/method/header form; Save endpoint adds
138
+ the profile without switching the connection. Select a saved endpoint or the
139
+ local fixture to activate it. Edit endpoint opens a separate draft; Cancel discards
140
+ it. Saving an active profile applies its changes, while saving another profile
141
+ keeps the active selection. Changing a profile URL clears its draft headers and
142
+ renames the saved entry on successful save. Duplicate saved URLs are rejected.
143
+
144
+ The demo persists URLs and methods and restores the active endpoint without
145
+ executing a query. Header values stay in memory per URL and are not restored after
146
+ reload. Public examples and `# sparql-endpoint` queries select their own connection
147
+ without inheriting stored session headers. The active URL below the editor has a
148
+ clipboard button with a brief copied checkmark. This manager is demo-owned host
149
+ code, not automatic persistence or credential management in `createHttpExecutor`.
package/docs/renderers.md CHANGED
@@ -748,6 +748,34 @@ order. Invalid host percentages throw at construction; a column-count mismatch
748
748
  falls back to equal widths at render time with a warning. Query widths override
749
749
  host defaults. No arbitrary CSS values are accepted as widths.
750
750
 
751
+ ### RDF details
752
+
753
+ Table defaults to readable lexical values. The **RDF details** (**RDF-details**)
754
+ toggle adds RDF notation: `<https://example.org>` for IRIs, `_:b1` for blank nodes,
755
+ `"Hallo wereld"@nl` for language-tagged literals, and `"42"^^xsd:integer` for typed
756
+ literals. Plain literals are quoted and unbound cells remain empty. Datatypes and
757
+ language tags use smaller superscript in the active theme's muted color; the full
758
+ original datatype IRI is available in the tooltip. XML Schema and RDF datatype
759
+ IRIs are abbreviated as `xsd:` and `rdf:`; other datatype IRIs are shown in full.
760
+ These display prefixes are predefined and do not depend on query prefix declarations.
761
+
762
+ ```ts
763
+ createTableRenderer({ showRdfDetails: true }); // Default: false.
764
+ ```
765
+
766
+ The exact lexical string, datatype and language from the endpoint are preserved;
767
+ no numeric/date conversion is performed. For example, a long integer remains
768
+ `"9223372036854775807"^^xsd:long`, and a float remains `"3.14"^^xsd:float` if those
769
+ are the endpoint's returned terms. The table cannot recover values or datatypes
770
+ that an endpoint has already converted. Quotes, newlines and backslashes are escaped
771
+ for display; RDF text is never interpreted as HTML.
772
+
773
+ The toggle choice is retained per result container for the renderer instance,
774
+ including rerenders and view switches. Other editor instances remain independent.
775
+ Changing it preserves filters, sort order, virtual scrolling and expanded resource
776
+ information. Filters, sorting, CSV downloads and the result model continue using
777
+ the original lexical values.
778
+
751
779
  ### Local DESCRIBE example
752
780
 
753
781
  The demo's **DESCRIBE-voorbeeld** explicitly selects local example data (no
@@ -788,7 +816,7 @@ const renderers = [createBooleanRenderer()];
788
816
 
789
817
  **Package:** `@ldforge/renderers` · **Factory:** `createJsonRenderer()` · **ID:** `json`
790
818
 
791
- Displays formatted JSON for debugging and inspecting RDF term metadata. This is LDForge's normalized `QueryResult` model, rather than the endpoint's raw JSON response. Literal text is never interpreted as HTML.
819
+ Displays formatted JSON in a read-only CodeMirror editor with syntax highlighting and line numbers. This is LDForge's normalized `QueryResult` model, rather than the endpoint's raw JSON response. Literal text is never interpreted as HTML. The Copy JSON button copies the complete result, including content outside the visible viewport, and briefly shows a checkmark and confirmation. Clipboard failures appear beside the button. The renderer cleans up its CodeMirror instance and feedback timer when the view is closed; query-editor height settings do not change this result view.
792
820
 
793
821
  **Binding contract:** supports `kind: 'bindings'`, `kind: 'boolean'` and `kind: 'graph'`. There are no required variable names. SELECT variables, RDF types, datatypes, language tags and unbound fields retain their normalized representation.
794
822
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ldforge/editor",
3
- "version": "0.1.8",
3
+ "version": "1.0.0",
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.8",
39
- "@ldforge/prefixes": "^0.1.8",
38
+ "@ldforge/core": "^1.0.0",
39
+ "@ldforge/prefixes": "^1.0.0",
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
@@ -8,10 +8,12 @@ export interface EditorControls {
8
8
  readonly prefixFolding?: boolean;
9
9
  readonly format?: boolean;
10
10
  readonly rendererWizard?: boolean;
11
+ readonly share?: boolean;
11
12
  readonly loadingIndicator?: boolean;
12
13
  readonly settings?: boolean;
13
14
  readonly language?: boolean;
14
15
  readonly fontSize?: boolean;
16
+ readonly autoGrow?: boolean;
15
17
  readonly tabs?: boolean;
16
18
  readonly addTab?: boolean;
17
19
  readonly renameTab?: boolean;
@@ -29,10 +31,12 @@ export function resolveControls(
29
31
  prefixFolding: true,
30
32
  format: true,
31
33
  rendererWizard: true,
34
+ share: true,
32
35
  loadingIndicator: true,
33
36
  settings: true,
34
37
  language: true,
35
38
  fontSize: true,
39
+ autoGrow: true,
36
40
  tabs: true,
37
41
  addTab: true,
38
42
  renameTab: true,
@@ -0,0 +1,42 @@
1
+ import type { Locale } from '@ldforge/core';
2
+
3
+ export const DEFAULT_EDITOR_ROWS = 15;
4
+ let controlNumber = 0;
5
+
6
+ export function validateEditorRows(rows: number): void {
7
+ if (!Number.isSafeInteger(rows) || rows < 1)
8
+ throw new RangeError('editorRows must be a positive safe integer.');
9
+ }
10
+
11
+ export function createAutoGrowControl(
12
+ doc: Document,
13
+ current: () => boolean,
14
+ locale: () => Locale,
15
+ onChange: (enabled: boolean) => void,
16
+ ) {
17
+ const element = doc.createElement('label');
18
+ element.className = 'ldforge-auto-grow';
19
+ const checkbox = doc.createElement('input');
20
+ checkbox.type = 'checkbox';
21
+ const copy = doc.createElement('span');
22
+ const text = doc.createElement('span');
23
+ text.id = `ldforge-auto-grow-label-${++controlNumber}`;
24
+ const description = doc.createElement('small');
25
+ description.id = `${text.id}-description`;
26
+ checkbox.setAttribute('aria-labelledby', text.id);
27
+ checkbox.setAttribute('aria-describedby', description.id);
28
+ copy.append(text, description);
29
+ element.append(checkbox, copy);
30
+ checkbox.addEventListener('change', () => onChange(checkbox.checked));
31
+ function refresh(): void {
32
+ text.textContent =
33
+ locale() === 'nl' ? 'Hele query tonen' : 'Show the full query';
34
+ description.textContent =
35
+ locale() === 'nl'
36
+ ? 'De editor wordt automatisch hoger, zodat je niet binnen de query hoeft te scrollen.'
37
+ : 'The editor expands automatically so you don’t have to scroll within the query.';
38
+ checkbox.checked = current();
39
+ }
40
+ refresh();
41
+ return { element, refresh };
42
+ }