@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.
- package/README.md +37 -0
- package/dist/controls.d.ts +2 -0
- package/dist/controls.d.ts.map +1 -1
- package/dist/controls.js +2 -0
- package/dist/controls.js.map +1 -1
- package/dist/editor-height.d.ts +8 -0
- package/dist/editor-height.d.ts.map +1 -0
- package/dist/editor-height.js +34 -0
- package/dist/editor-height.js.map +1 -0
- package/dist/index.d.ts +33 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +347 -33
- package/dist/index.js.map +1 -1
- package/dist/renderer-info.d.ts +4 -0
- package/dist/renderer-info.d.ts.map +1 -0
- package/dist/renderer-info.js +41 -0
- package/dist/renderer-info.js.map +1 -0
- package/dist/renderer-wizard.d.ts.map +1 -1
- package/dist/renderer-wizard.js +109 -25
- package/dist/renderer-wizard.js.map +1 -1
- package/dist/share.d.ts +16 -0
- package/dist/share.d.ts.map +1 -0
- package/dist/share.js +113 -0
- package/dist/share.js.map +1 -0
- package/dist/sparql/completion.d.ts.map +1 -1
- package/dist/sparql/completion.js +5 -0
- package/dist/sparql/completion.js.map +1 -1
- package/dist/styles.css +496 -82
- package/dist/tab-api.d.ts +7 -1
- package/dist/tab-api.d.ts.map +1 -1
- package/dist/tab-api.js +29 -1
- package/dist/tab-api.js.map +1 -1
- package/dist/theme.d.ts +4 -0
- package/dist/theme.d.ts.map +1 -0
- package/dist/theme.js +73 -0
- package/dist/theme.js.map +1 -0
- package/docs/api/configuration.md +72 -21
- package/docs/api/editor.md +184 -19
- package/docs/api/overview.md +8 -0
- package/docs/api/plugins.md +6 -2
- package/docs/api/tab.md +37 -9
- package/docs/api/transport.md +19 -2
- package/docs/renderers.md +29 -1
- package/package.json +3 -3
- package/src/controls.ts +4 -0
- package/src/editor-height.ts +42 -0
- package/src/index.ts +440 -30
- package/src/renderer-info.ts +52 -0
- package/src/renderer-wizard.ts +114 -25
- package/src/share.ts +125 -0
- package/src/sparql/completion.ts +5 -0
- package/src/styles.css +496 -82
- package/src/tab-api.ts +44 -4
- package/src/theme.ts +87 -0
package/docs/api/overview.md
CHANGED
|
@@ -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({
|
package/docs/api/plugins.md
CHANGED
|
@@ -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
|
-
|
|
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
|
|
19
|
-
| ------------------------------- |
|
|
20
|
-
| `getQuery()` | `string`
|
|
21
|
-
| `setQuery(query)` | `void`
|
|
22
|
-
| `formatQuery(options?)` | `Promise<string>`
|
|
23
|
-
| `
|
|
24
|
-
| `
|
|
25
|
-
| `
|
|
26
|
-
| `
|
|
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
|
+
```
|
package/docs/api/transport.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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.
|
|
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.
|
|
39
|
-
"@ldforge/prefixes": "^0.
|
|
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
|
+
}
|