@pngwasi/config-editor 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +1985 -2
- package/binding.d.ts +216 -0
- package/binding.js +634 -0
- package/index.d.ts +41 -0
- package/index.js +14 -0
- package/load.d.ts +18 -0
- package/load.js +57 -0
- package/package.json +70 -4
- package/pkg/config_editor.d.ts +2500 -0
- package/pkg/config_editor.js +3281 -0
- package/pkg/config_editor_bg.wasm +0 -0
- package/pkg/config_editor_bg.wasm.d.ts +110 -0
- package/preset.css +2899 -0
- package/setting-types.js +24 -0
- package/tools.d.ts +23 -0
- package/tools.js +19 -0
package/README.md
CHANGED
|
@@ -1,3 +1,1986 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Config Editor for JavaScript
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A fast, schema-aware config editor for the browser: YAML, JSON, TOML, HCL and XML, or a language of your own,
|
|
4
|
+
with completion from a JSON Schema, hover docs, validation, a diff gutter,
|
|
5
|
+
editing one language as another, and eleven themes. It is written in Rust
|
|
6
|
+
([`config-editor-leptos`](https://github.com/paradoxe35/config-editor/tree/main/crates/config-editor-leptos))
|
|
7
|
+
and ships as WebAssembly; this package is its framework-free JavaScript API.
|
|
8
|
+
|
|
9
|
+
It has three entries:
|
|
10
|
+
|
|
11
|
+
| Entry | For |
|
|
12
|
+
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
13
|
+
| `@pngwasi/config-editor` | An app: `loadConfigEditor`, `ConfigEditor`, `ConfigDocuments`, and the language and theme catalogs (`languages`, `themes`, `languageForFile`, `registerLanguage`). |
|
|
14
|
+
| `@pngwasi/config-editor/tools` | Text without an editor (servers, build steps, review screens): validation, conversion, parsing, diffs, paths, folds; see [Tools](#pngwasiconfig-editortools). |
|
|
15
|
+
| `@pngwasi/config-editor/binding` | Writing a package for another framework; see [Binding](#pngwasiconfig-editorbinding). |
|
|
16
|
+
|
|
17
|
+
For React, Vue and Svelte, use [`@pngwasi/config-editor-react`](https://github.com/paradoxe35/config-editor/tree/main/js/config-editor-react),
|
|
18
|
+
[`@pngwasi/config-editor-vue`](https://github.com/paradoxe35/config-editor/tree/main/js/config-editor-vue)
|
|
19
|
+
or [`@pngwasi/config-editor-svelte`](https://github.com/paradoxe35/config-editor/tree/main/js/config-editor-svelte),
|
|
20
|
+
which build on this package.
|
|
21
|
+
|
|
22
|
+
<!-- toc -->
|
|
23
|
+
|
|
24
|
+
## Contents
|
|
25
|
+
|
|
26
|
+
- [Install](#install)
|
|
27
|
+
- [Quick start](#quick-start)
|
|
28
|
+
- [Loading the WebAssembly](#loading-the-webassembly)
|
|
29
|
+
- [`new ConfigEditor(element, options)`](#new-configeditorelement-options)
|
|
30
|
+
- [Settings](#settings)
|
|
31
|
+
- [Built-in texts](#built-in-texts)
|
|
32
|
+
- [`update(options)`](#updateoptions)
|
|
33
|
+
- [Instance members](#instance-members)
|
|
34
|
+
- [Host diagnostics](#host-diagnostics)
|
|
35
|
+
- [Read-only fields](#read-only-fields)
|
|
36
|
+
- [Secrets](#secrets)
|
|
37
|
+
- [Paths](#paths)
|
|
38
|
+
- [Languages and themes](#languages-and-themes)
|
|
39
|
+
- [XML mapping](#xml-mapping)
|
|
40
|
+
- [`@pngwasi/config-editor/tools`](#pngwasiconfig-editortools)
|
|
41
|
+
- [`@pngwasi/config-editor/binding`](#pngwasiconfig-editorbinding)
|
|
42
|
+
- [Keyboard](#keyboard)
|
|
43
|
+
- [Leaving the editor and screen readers](#leaving-the-editor-and-screen-readers)
|
|
44
|
+
- [Folding](#folding)
|
|
45
|
+
- [Sticky scroll](#sticky-scroll)
|
|
46
|
+
- [Saving and unsaved edits](#saving-and-unsaved-edits)
|
|
47
|
+
- [Several documents](#several-documents)
|
|
48
|
+
- [Reviewing changes](#reviewing-changes)
|
|
49
|
+
- [Custom languages](#custom-languages)
|
|
50
|
+
- [Schema completion and hover](#schema-completion-and-hover)
|
|
51
|
+
- [Strings and comments over lines](#strings-and-comments-over-lines)
|
|
52
|
+
- [Edit-as with a custom language](#edit-as-with-a-custom-language)
|
|
53
|
+
- [Themes](#themes)
|
|
54
|
+
- [Styling](#styling)
|
|
55
|
+
- [Size](#size)
|
|
56
|
+
- [Strict Content-Security-Policy](#strict-content-security-policy)
|
|
57
|
+
- [License](#license)
|
|
58
|
+
|
|
59
|
+
<!-- /toc -->
|
|
60
|
+
|
|
61
|
+
## Install
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
npm install @pngwasi/config-editor
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Browsers only (ES modules + WebAssembly). The `.wasm` file is about 2.3 MB
|
|
68
|
+
gzipped (1.5 MB with brotli) and loads once per page. It is built with every Cargo feature of
|
|
69
|
+
the Rust crate (all five languages, schema validation, find and replace,
|
|
70
|
+
the diff, folding, read-only fields and secrets); a Rust app can leave out
|
|
71
|
+
what it does not use ([Cargo features](https://github.com/paradoxe35/config-editor/tree/main/crates/config-editor-leptos#cargo-features)).
|
|
72
|
+
|
|
73
|
+
## Quick start
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
import { ConfigEditor, loadConfigEditor } from "@pngwasi/config-editor";
|
|
77
|
+
|
|
78
|
+
await loadConfigEditor();
|
|
79
|
+
|
|
80
|
+
const editor = new ConfigEditor(document.getElementById("config")!, {
|
|
81
|
+
language: "yaml",
|
|
82
|
+
value: "listen: 7835\n",
|
|
83
|
+
schema: await (await fetch("/schema.json")).text(),
|
|
84
|
+
showToolbar: true,
|
|
85
|
+
showFooter: true,
|
|
86
|
+
onChange: (text) => save(text),
|
|
87
|
+
});
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Loading the WebAssembly
|
|
91
|
+
|
|
92
|
+
`loadConfigEditor()` loads the WebAssembly module, once for the whole page
|
|
93
|
+
however many callers ask (the framework components call it themselves).
|
|
94
|
+
Await it before creating an editor or calling a [tool](#pngwasiconfig-editortools).
|
|
95
|
+
It fetches `config_editor_bg.wasm` next to the package's JavaScript, which
|
|
96
|
+
works with bundlers that copy it (Vite, webpack 5, Parcel). When yours does
|
|
97
|
+
not, pass its URL:
|
|
98
|
+
|
|
99
|
+
```js
|
|
100
|
+
import { loadConfigEditor } from "@pngwasi/config-editor";
|
|
101
|
+
|
|
102
|
+
// Vite
|
|
103
|
+
import wasmUrl from "@pngwasi/config-editor/config_editor_bg.wasm?url";
|
|
104
|
+
await loadConfigEditor({ module_or_path: wasmUrl });
|
|
105
|
+
|
|
106
|
+
// Any server: copy node_modules/@pngwasi/config-editor/pkg/config_editor_bg.wasm
|
|
107
|
+
await loadConfigEditor({ module_or_path: "/assets/config_editor_bg.wasm" });
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
A failed load is not kept: calling it again (with the right URL) retries,
|
|
111
|
+
and framework components whose own load failed mount then.
|
|
112
|
+
|
|
113
|
+
## `new ConfigEditor(element, options)`
|
|
114
|
+
|
|
115
|
+
Mounts an editor into `element` (an `HTMLElement`; its previous content is
|
|
116
|
+
replaced, editors included). Options are type-checked: a value of the wrong type
|
|
117
|
+
throws, and an unknown option name is reported in the console. They are the
|
|
118
|
+
document and its callbacks (below) and every [setting](#settings) (`theme`,
|
|
119
|
+
`showFooter`, `folding`, …).
|
|
120
|
+
|
|
121
|
+
| Option | Type | Default | Purpose |
|
|
122
|
+
| -------------------- | ------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
123
|
+
| `language` | `string` | `"yaml"` | Language of the document: `"yaml"`, `"json"`, `"toml"`, `"hcl"`, `"xml"` (any case, or a file extension such as `"yml"` or `"tf"`), or a registered one. `value`, `baseline` and `onChange` are always in it. |
|
|
124
|
+
| `value` | `string` | `""` | The document. |
|
|
125
|
+
| `editAs` | `string` | — | Show and edit the document in another language; it is saved back in `language`, keeping its comments. |
|
|
126
|
+
| `schema` | `string` | — | JSON Schema as JSON or YAML text: completion, hover docs and validation. |
|
|
127
|
+
| `baseline` | `string` | `value` | Text the diff gutter compares against: the version last saved or loaded. See [Saving](#saving-and-unsaved-edits). |
|
|
128
|
+
| `readOnly` | `boolean` | `false` | View mode: navigation, selection, diagnostics and hover keep working. |
|
|
129
|
+
| `readOnlyReason` | `string` | — | Why the editor is read-only, while `readOnly` is on: the "Cannot edit in a read-only editor" notice says it when the user tries to edit, and so does the text area's accessible description. `update` changes it (`null`: no reason). |
|
|
130
|
+
| `fileName` | `string` | `untitled.<ext>` | Shown in the toolbar. |
|
|
131
|
+
| `className` | `string` | — | Extra class on the editor root. |
|
|
132
|
+
| `echoes` | `boolean` | `false` | Set it when you hand every `onChange` text back through `update({ value })`, possibly late and in any order; see [Hosts that echo](#hosts-that-echo). Fixed for the editor's life. |
|
|
133
|
+
| `channel` | `HostChannel` | — | The `channel` of an editor this one replaces (a framework re-creating its editor): its echoes still on their way are this editor's too, and with no `readOnlyRanges` given it holds that editor's ranges where they are now. The framework components pass it themselves. |
|
|
134
|
+
| `onChange` | `(value: string) => void` | — | Called with the document after every edit (after each typing pause while editing as another language). |
|
|
135
|
+
| `onEditAsChange` | `(language: string) => void` | — | Called with the language on screen: once on mount, then each time an `editAs` switch completes and when undo or redo steps back across one (a switch is an undo step). A switch waits while the document cannot convert yet (TOML has no `null`): until then the host's language stays on screen, edited and sent to `onChange` as it is, with the reason on the value in the way. Label the language shown from this, not from `editAs`. |
|
|
136
|
+
| `onSyncChange` | `(inSync: boolean) => void` | — | Called with whether the text on screen is written back to the document: once on mount, then each time that changes. `false` while an `editAs` edit cannot convert back (a `null` for TOML, or a value `language` would read back differently, such as a list typed over an XML string; `value` stays the last document, `onChange` waits and `save()` sends nothing; a list the document held, left with one item or none, is written as `language` writes it), whatever brought it there (typing, paste, undo, a switch, a reload, a new `value`); read after each typing pause. Always `true` in `language`. |
|
|
137
|
+
| `onChangeSummary` | `(summary: ChangeSummary) => void` | — | Called with `{ added, removed, modified, hunks }`: the lines changed against `baseline` and the number of separate changes, on mount and whenever it changes. |
|
|
138
|
+
| `onProblems` | `(problems: Diagnostic[]) => void` | — | Called with the editor's own problems (syntax, schema, secret placeholders, values Edit-as cannot convert; `origin: "editor"`), never `hostDiagnostics`: once on mount, then each time they change after a pause in typing, not while they stay the same. With `showDiagnostics` off it finds none. To gate a Save button, use what `save()` returns, not an `error` here: a lone CR in a TOML or HCL text is shown as an `error` and still saves. |
|
|
139
|
+
| `hostDiagnostics` | `HostDiagnostic[]` | — | Problems the host found (its own checks: a service, a build step), shown with the editor's own; see [Host diagnostics](#host-diagnostics). |
|
|
140
|
+
| `onPathChange` | `(path: EditorPath) => void` | — | Called with the path of what the caret is on each time it changes (and once on mount), for a breadcrumb; see [Paths](#paths). The path is computed only while this is set. |
|
|
141
|
+
| `onSchemaWarning` | `(message: string) => void` | console warning | Called once per thing in `schema` the editor cannot use, such as a `patternProperties` regex its engine cannot compile (keys it matches get no completions or hover docs). Called a microtask after `new ConfigEditor` returns, never inside it, so the instance is yours by then. |
|
|
142
|
+
| `readOnlyPaths` | `FieldPath[]` | — | Fields the user cannot change (each with everything inside it), on top of the schema's `readOnly` ones; see [Read-only fields](#read-only-fields). |
|
|
143
|
+
| `readOnlyRanges` | `TextRangeInput[]` | — | Stretches of the document (in `language`) the user cannot change: `{ start, end }` string indices or one-based `{ startLine, startColumn, endLine?, endColumn? }`. |
|
|
144
|
+
| `rangesFor` | `string` | `value` | The text `readOnlyRanges` and host `range`s were worked out for, when it is not `value` (a check of a text the document has moved past): they are checked in it and moved to `value`, a range around a change growing over it. |
|
|
145
|
+
| `secrets` | `SecretOptions` | defaults | `{ placeholder?, isPlaceholder?, hint?, referencePrefixes? }`: how secret placeholders are matched, described and completed; see [Secrets](#secrets). |
|
|
146
|
+
| `onSave` | `(value: string, language: string) => void` | — | Called on `Ctrl+S` / `Cmd+S` (the browser's dialog prevented) and `save()`, with the document in `language`. Nothing saves by itself. Without it, `Ctrl+S` is the browser's. |
|
|
147
|
+
| `onDirtyChange` | `(dirty: boolean) => void` | — | Called with whether the document differs from `baseline`: once on mount, then each time that changes. |
|
|
148
|
+
| `onBaselineConflict` | `(event: BaselineConflict) => void` | — | Called when a new `baseline` arrives under unsaved edits (`"opened"`) and when that is settled (`"reloaded"`, `"kept-mine"`, `"settled"`). |
|
|
149
|
+
|
|
150
|
+
An unknown language, theme or color token, or an invalid schema, throws an
|
|
151
|
+
`Error` saying which.
|
|
152
|
+
|
|
153
|
+
`value`, `baseline`, `editAs`, `readOnly`, `hostDiagnostics`, the read-only
|
|
154
|
+
fields, the callbacks and every setting change live through
|
|
155
|
+
[`update`](#updateoptions). The other options (`language`, `schema`,
|
|
156
|
+
`fileName`, `className`, `secrets`, `echoes`) are what the editor is built from:
|
|
157
|
+
create a new one to change them (the framework components do it for you).
|
|
158
|
+
|
|
159
|
+
### Settings
|
|
160
|
+
|
|
161
|
+
The settings are the theme, the colors and every on/off switch: the
|
|
162
|
+
`EditorSettings` type, generated from the Rust crate's struct, each with a
|
|
163
|
+
default. Give them with the other options, and switch any of them live with
|
|
164
|
+
`update`: the caret, the undo history and the folds stay. `update` merges
|
|
165
|
+
them key by key (a setting left out stays as it is, one set to `null`
|
|
166
|
+
returns to its default); `settings` returns them, every key set.
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
// A plain viewer: no colors, no diff, no suggestions, no popups.
|
|
170
|
+
const viewer = new ConfigEditor(element, {
|
|
171
|
+
value: text,
|
|
172
|
+
readOnly: true,
|
|
173
|
+
highlighting: false,
|
|
174
|
+
showDiff: false,
|
|
175
|
+
completions: false,
|
|
176
|
+
hoverDocs: false,
|
|
177
|
+
showDiagnostics: false,
|
|
178
|
+
});
|
|
179
|
+
|
|
180
|
+
// Later: one setting changed, the rest kept.
|
|
181
|
+
viewer.update({ showDiagnostics: true });
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
<!-- settings:start -->
|
|
185
|
+
|
|
186
|
+
<!-- Generated from crates/config-editor-leptos/src/settings.rs by js/config-editor/tests/settings.rs; do not edit. Regenerate with `UPDATE_GENERATED=1 cargo test -p config-editor-js --test settings`. -->
|
|
187
|
+
|
|
188
|
+
| Setting | Default | |
|
|
189
|
+
| ------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
190
|
+
| `theme` | `"vscode-dark"` | The bundled color theme. |
|
|
191
|
+
| `colors` | none | Colors overriding the theme's, by token (`bg`, `key`, `string`, `selection`, …), for a custom palette. |
|
|
192
|
+
| `styled` | `true` | Inject the preset stylesheet. Off, serve it as a file (`preset.css` in the crate and the npm package, as a strict Content-Security-Policy needs) or style the `config-editor__*` markup yourself (the preset is `PRESET_CSS`, `presetCss()` in JavaScript). |
|
|
193
|
+
| `showToolbar` | `false` | Show the built-in toolbar: the file name, its language and the schema's state. |
|
|
194
|
+
| `showFooter` | `false` | Show the built-in status footer: the suggestions hint, problem and change counts, and the line count. |
|
|
195
|
+
| `showDiagnostics` | `true` | Show syntax and schema problems inline, in the footer and on hover (`F8` moves between them). |
|
|
196
|
+
| `showDiff` | `true` | Show line changes against the baseline in the gutter (`Alt+F5` / `Alt+F3` move between them). Off, the change summary stays at zero. In Rust, needs the `diff` Cargo feature. |
|
|
197
|
+
| `completions` | `true` | Schema completions (`Ctrl+Space`). |
|
|
198
|
+
| `autoTriggerCompletions` | `true` | Open suggestions while typing and after accepting a key. Off, only `Ctrl+Space` opens them. |
|
|
199
|
+
| `hoverDocs` | `true` | Show the schema's title, description, type, default and examples when hovering a key, at the caret with `Ctrl+K Ctrl+I` (read to screen readers), or on a tap on a touch screen. |
|
|
200
|
+
| `highlighting` | `true` | Syntax colors. |
|
|
201
|
+
| `autoClosing` | `true` | Auto-close quotes and brackets, wrap selections, and delete empty pairs on Backspace. |
|
|
202
|
+
| `search` | `true` | Find and replace (`Ctrl+F`, `Ctrl+H`, `F3`). Off, those keys are left to the browser. In Rust, needs the `search` Cargo feature. |
|
|
203
|
+
| `goToLine` | `true` | Go to line (`Ctrl+G`). Off, the key is left to the browser. In Rust, needs the `search` Cargo feature. |
|
|
204
|
+
| `folding` | `true` | Folding by structure: chevrons in the gutter, `Ctrl+Shift+[` and `Ctrl+Shift+]` at the caret, `Ctrl+K Ctrl+0` and `Ctrl+K Ctrl+J` for everything (`Cmd` on macOS). View only: the text stays whole. Switching it off opens every fold. In Rust, needs the `folding` Cargo feature. |
|
|
205
|
+
| `stickyScroll` | `true` | Sticky scroll, as in VS Code: the lines opening the blocks around the top line stay at the top while the text scrolls; a click goes back to one. Works with `folding` off too. In Rust, needs the `folding` Cargo feature. |
|
|
206
|
+
| `stickyScrollMaxLines` | `5` | The most lines sticky scroll shows, 1 to 20 (others are taken as the nearest), and never more than fit in a quarter of the text area (at least one). |
|
|
207
|
+
| `saveShortcut` | `true` | Whether `Ctrl+S` / `Cmd+S` saves, when a save callback is set. Off, the key is left to the browser and only the handle's `save` saves. |
|
|
208
|
+
| `strings` | English (see below) | Every built-in text (hints, tooltips, notices and their buttons, footer counts, accessible names and announcements), English by default: give only the texts to change. See `EditorStrings`. |
|
|
209
|
+
|
|
210
|
+
<!-- settings:end -->
|
|
211
|
+
|
|
212
|
+
### Built-in texts
|
|
213
|
+
|
|
214
|
+
`strings` rewords or translates every text the editor writes itself
|
|
215
|
+
(hints, tooltips, notices, footer counts, accessible names, the messages of
|
|
216
|
+
the problems it words). Give only the texts to change; the others keep their
|
|
217
|
+
English defaults, and an unknown key is warned about in the console:
|
|
218
|
+
|
|
219
|
+
```js
|
|
220
|
+
const editor = new ConfigEditor(element, {
|
|
221
|
+
value,
|
|
222
|
+
strings: {
|
|
223
|
+
noProblems: "Keine Fehler",
|
|
224
|
+
errorsOne: "{count} Fehler",
|
|
225
|
+
errorsOther: "{count} Fehler",
|
|
226
|
+
},
|
|
227
|
+
});
|
|
228
|
+
// Live, like every setting: the texts given change, the others stay.
|
|
229
|
+
editor.update({ strings: { find: "Suchen" } });
|
|
230
|
+
// `null` returns one text, or all of them, to the English default.
|
|
231
|
+
editor.update({ strings: { find: null } });
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Placeholders are written in braces (`{count}`, `{line}`); a text takes the
|
|
235
|
+
placeholders of its default, and the editor warns in the console about any
|
|
236
|
+
other. Counts come in pairs: `…One` for 1, `…Other` for any other count.
|
|
237
|
+
|
|
238
|
+
While editing as another language (`editAs`), a notice under the toolbar says
|
|
239
|
+
what that language does not show or keep: the host file's comments and
|
|
240
|
+
formatting are not shown there and saving keeps them, and comments typed there
|
|
241
|
+
are never saved. Its texts are `editAsHostComments` (`editAsHostInstructions`
|
|
242
|
+
for an XML file with processing instructions), `editAsTypedComments` and
|
|
243
|
+
`editAsTypedCommentsNone`.
|
|
244
|
+
|
|
245
|
+
YAML tags (`!Sub 'x-${y}'`, `!GetAtt [a, b]`, `!include`, `!secret`,
|
|
246
|
+
`!reference`) are valid YAML: the data (what the schema validates, `parse`
|
|
247
|
+
returns and other languages show) is the value under the tag, a tagged
|
|
248
|
+
scalar as its text, and the tag stays in the YAML through every edit. An
|
|
249
|
+
edit the tag cannot follow (a tagged map replaced by a number) waits, naming
|
|
250
|
+
the tag. Several YAML documents in one text (`---` between them) are one per
|
|
251
|
+
file here: the problem shows at the second `---`, and `editAs` is refused
|
|
252
|
+
with that reason.
|
|
253
|
+
|
|
254
|
+
<!-- strings:start -->
|
|
255
|
+
|
|
256
|
+
<!-- Generated from crates/config-editor-leptos/src/strings.rs by js/config-editor/tests/settings.rs; do not edit. Regenerate with `UPDATE_GENERATED=1 cargo test -p config-editor-js --test settings`. -->
|
|
257
|
+
|
|
258
|
+
<details>
|
|
259
|
+
<summary>Every text and its default (229 texts)</summary>
|
|
260
|
+
|
|
261
|
+
| Key | Default | |
|
|
262
|
+
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
263
|
+
| `suggestionsHint` | `"{key} for suggestions"` | The footer's suggestions hint; `{key}` is where the chord goes. |
|
|
264
|
+
| `suggestionsHintTouch` | `"suggestions appear as you type"` | `suggestionsHint` on a touch screen, which has no `suggestionsKey`; shown only while suggestions open as you type. |
|
|
265
|
+
| `suggestionsKey` | `"Ctrl+Space"` | The chord that opens suggestions, as the footer draws it: keys between `+`. |
|
|
266
|
+
| `noProblems` | `"No errors"` | The footer's problem count when there are none. |
|
|
267
|
+
| `errorsOne` | `"{count} error"` | One error, in the footer's problem count. |
|
|
268
|
+
| `errorsOther` | `"{count} errors"` | Several errors, in the footer's problem count. |
|
|
269
|
+
| `warningsOne` | `"{count} warning"` | One warning, in the footer's problem count. |
|
|
270
|
+
| `warningsOther` | `"{count} warnings"` | Several warnings, in the footer's problem count. |
|
|
271
|
+
| `infosOne` | `"{count} info"` | One info, in the footer's problem count. |
|
|
272
|
+
| `infosOther` | `"{count} info"` | Several infos, in the footer's problem count. |
|
|
273
|
+
| `hintsOne` | `"{count} hint"` | One hint, in the footer's problem count. |
|
|
274
|
+
| `hintsOther` | `"{count} hints"` | Several hints, in the footer's problem count. |
|
|
275
|
+
| `problemsHint` | `"hover or focus underlined text"` | After the problem count when every problem has its place. |
|
|
276
|
+
| `problemsHintTouch` | `"tap underlined text"` | `problemsHint` on a touch screen, which has no hover. |
|
|
277
|
+
| `problemsCut` | `"only the editor's first {count} are shown"` | After the problem count when the editor's own problems were cut; `{count}` is how many of them are shown (the host's are all shown). |
|
|
278
|
+
| `problemsMore` | `"Only the first {count} problems are shown; more follow."` | The problem that says the list was cut, after `{count}` problems. |
|
|
279
|
+
| `problemsIncomplete` | `"The schema check stopped early; more problems may follow."` | The problem that says the schema check stopped early, so more problems may follow than are listed (a schema whose explanation would grow faster than the document). |
|
|
280
|
+
| `underlinesCut` | `"only {count} underlines are drawn, the most serious first"` | After the problem count when the problems have more underlines than are drawn; `{count}` is how many are (the most serious first). |
|
|
281
|
+
| `changesOne` | `"{count} change"` | The footer's change count against the baseline, for one change. |
|
|
282
|
+
| `changesOther` | `"{count} changes"` | The footer's change count, for several changes. |
|
|
283
|
+
| `changeDetailsOne` | `"{lines} line · Alt+F5 for the next"` | The change count's tooltip when one line changed; `{lines}` lists the added, modified and removed counts. |
|
|
284
|
+
| `changeDetailsOther` | `"{lines} lines · Alt+F5 for the next"` | The change count's tooltip when several lines changed. |
|
|
285
|
+
| `changedAdded` | `"{count} added"` | Added lines, in the change count's tooltip. |
|
|
286
|
+
| `changedModified` | `"{count} modified"` | Modified lines, in the change count's tooltip. |
|
|
287
|
+
| `changedRemoved` | `"{count} removed"` | Removed lines, in the change count's tooltip. |
|
|
288
|
+
| `linesOne` | `"{count} line"` | The footer's line count, for one line. |
|
|
289
|
+
| `linesOther` | `"{count} lines"` | The footer's line count, for several lines. |
|
|
290
|
+
| `tabFocus` | `"Tab moves focus"` | The footer's indicator while Tab moves the focus. |
|
|
291
|
+
| `tabFocusTitle` | `"Tab moves focus (Ctrl+M to indent with Tab)"` | Its tooltip; clicking it turns the mode off. |
|
|
292
|
+
| `tabFocusOn` | `"Tab moves focus: Tab and Shift+Tab now leave the editor. Ctrl+M to indent with Tab again."` | Announced when `Ctrl+M` makes Tab move the focus. |
|
|
293
|
+
| `tabFocusOff` | `"Tab indents: Tab and Shift+Tab indent again. Ctrl+M to move focus with Tab."` | Announced when `Ctrl+M` makes Tab indent again. |
|
|
294
|
+
| `schemaConnected` | `"Schema connected"` | The toolbar's schema state. |
|
|
295
|
+
| `editAsHostComments` | `"The {host} file's comments and formatting are not shown while editing as {edit}; saving keeps them."` | The Edit-as notice when the host's file has comments, which the edited language does not show but saving keeps. |
|
|
296
|
+
| `editAsHostInstructions` | `"The {host} file's comments, processing instructions and formatting are not shown while editing as {edit}; saving keeps them."` | The same when the host's file has processing instructions too (XML `<?…?>`), which the edited language does not show either. |
|
|
297
|
+
| `editAsTypedComments` | `"Comments typed in {edit} are not saved: the {host} file keeps only its own comments."` | The Edit-as notice when comments are typed in the edited language, which saving drops, and the host's language has comments. |
|
|
298
|
+
| `editAsTypedCommentsNone` | `"Comments typed in {edit} are not saved: {host} has no comments."` | The same when the host's language has no comments (JSON). |
|
|
299
|
+
| `editAsDismiss` | `"Dismiss"` | The Edit-as notice's close button. |
|
|
300
|
+
| `baselineChanged` | `"This file changed outside the editor."` | The notice shown when the host's baseline changes under unsaved edits. |
|
|
301
|
+
| `baselineChangedDetail` | `"Reload it, losing your changes, or keep your text and compare it with the new version."` | What the notice's choices do, after its message. |
|
|
302
|
+
| `reload` | `"Reload"` | The notice's button that takes the new baseline as the text. |
|
|
303
|
+
| `reloaded` | `"Reloaded"` | Announced after Reload took the changed baseline. |
|
|
304
|
+
| `reloadTitle` | `"Replace your text with the new version ({cmd}+Z brings yours back)"` | Its tooltip. |
|
|
305
|
+
| `keepMine` | `"Keep mine"` | The notice's button that keeps the text against the new baseline. |
|
|
306
|
+
| `keepMineTitle` | `"Keep your text; the changes are now shown against the new version (Escape)"` | Its tooltip. |
|
|
307
|
+
| `baselineChangedKeys` | `"In the editor, F6 moves to the choices and back."` | How to reach the notice's choices from the keyboard, shown on it (and announced with it); not on touch screens. |
|
|
308
|
+
| `findWidget` | `"Find and replace"` | The find widget's accessible name. |
|
|
309
|
+
| `toggleReplace` | `"Toggle replace"` | The button showing the replace row. |
|
|
310
|
+
| `toggleReplaceTitle` | `"Toggle replace ({cmd}+H)"` | Its tooltip. |
|
|
311
|
+
| `find` | `"Find"` | The query field's accessible name and placeholder. |
|
|
312
|
+
| `matchCase` | `"Match case"` | The match-case toggle. |
|
|
313
|
+
| `matchCaseTitle` | `"Match case (Alt+C)"` | Its tooltip. |
|
|
314
|
+
| `wholeWord` | `"Match whole word"` | The whole-word toggle. |
|
|
315
|
+
| `wholeWordTitle` | `"Match whole word (Alt+W)"` | Its tooltip. |
|
|
316
|
+
| `useRegex` | `"Use regular expression"` | The regular-expression toggle. |
|
|
317
|
+
| `useRegexTitle` | `"Use regular expression (Alt+R)"` | Its tooltip. |
|
|
318
|
+
| `previousMatch` | `"Previous match"` | The previous-match button. |
|
|
319
|
+
| `previousMatchTitle` | `"Previous match (Shift+Enter)"` | Its tooltip. |
|
|
320
|
+
| `nextMatch` | `"Next match"` | The next-match button. |
|
|
321
|
+
| `nextMatchTitle` | `"Next match (Enter)"` | Its tooltip. |
|
|
322
|
+
| `close` | `"Close"` | The find widget's close button. |
|
|
323
|
+
| `closeTitle` | `"Close (Escape)"` | Its tooltip. |
|
|
324
|
+
| `replace` | `"Replace"` | The replacement field's accessible name and placeholder, and the button replacing the current match. |
|
|
325
|
+
| `replaceTitle` | `"Replace (Enter)"` | The replace button's tooltip. |
|
|
326
|
+
| `replaceAll` | `"All"` | The replace-all button. |
|
|
327
|
+
| `replaceAllLabel` | `"Replace all"` | Its accessible name. |
|
|
328
|
+
| `replaceAllTitle` | `"Replace all ({cmd}+Alt+Enter)"` | Its tooltip. |
|
|
329
|
+
| `matchPosition` | `"{current} of {total}"` | The match count: match `{current}` of `{total}`. |
|
|
330
|
+
| `noResults` | `"No results"` | The match count when nothing matches. |
|
|
331
|
+
| `invalidPattern` | `"Invalid pattern"` | The match count when the regular expression is invalid. |
|
|
332
|
+
| `replacedOne` | `"Replaced {count} occurrence"` | After Replace All, for one match. |
|
|
333
|
+
| `replacedOther` | `"Replaced {count} occurrences"` | After Replace All, for several. |
|
|
334
|
+
| `replaceSkipped` | `"; skipped {count} in read-only text or secret placeholders"` | Added when Replace All left matches in protected text alone. |
|
|
335
|
+
| `nothingReplaced` | `"Every match is in read-only text or secret placeholders; nothing was replaced"` | After Replace All when every match is in read-only text or a secret placeholder. |
|
|
336
|
+
| `goToLine` | `"Go to line"` | The go-to-line field's accessible name. |
|
|
337
|
+
| `goToLinePlaceholder` | `"line or line:column"` | Its placeholder. |
|
|
338
|
+
| `goToLineHint` | `"Line 1–{lines}, or line:column"` | Its hint: the range of lines. |
|
|
339
|
+
| `goToLineInvalid` | `"Type a line number between 1 and {lines}"` | Its hint when the text is no position. |
|
|
340
|
+
| `addedLine` | `"Added line"` | The change preview's title for an added line. |
|
|
341
|
+
| `modifiedLine` | `"Modified line"` | For a modified line. |
|
|
342
|
+
| `removedLine` | `"Removed line"` | For one removed line. |
|
|
343
|
+
| `removedLines` | `"Removed lines"` | For several removed lines. |
|
|
344
|
+
| `removedLineAtEnd` | `"Removed line at end of document"` | For one line removed after the last one. |
|
|
345
|
+
| `removedLinesAtEnd` | `"Removed lines at end of document"` | For several lines removed after the last one. |
|
|
346
|
+
| `showAdded` | `"Show added line {line}"` | The gutter marker of an added line. |
|
|
347
|
+
| `showAddedTitle` | `"Show added line"` | Its tooltip. |
|
|
348
|
+
| `showModified` | `"Show before and after for modified line {line}"` | The gutter marker of a modified line. |
|
|
349
|
+
| `showModifiedTitle` | `"Show before and after"` | Its tooltip. |
|
|
350
|
+
| `showRemoved` | `"Show removed lines before line {line}"` | The gutter marker of removed lines. |
|
|
351
|
+
| `showRemovedTitle` | `"Show removed lines"` | Its tooltip, and that of lines removed at the end. |
|
|
352
|
+
| `showRemovedAtEnd` | `"Show removed lines at end of document"` | The gutter marker of lines removed after the last one. |
|
|
353
|
+
| `previewHeading` | `"{title} · line {line}"` | The change preview's heading: its `{title}` and `{line}`. |
|
|
354
|
+
| `previewLabel` | `"{title}, line {line}"` | The change preview's accessible name. |
|
|
355
|
+
| `changePosition` | `"{title}, line {line}: change {position} of {total}"` | Announced on `Alt+F5` / `Shift+Alt+F5`: the change's `{title}` (as the preview's), its `{line}`, and its `{position}` of `{total}`. |
|
|
356
|
+
| `noChanges` | `"No changes"` | Announced on `Alt+F5` / `Alt+F3` when nothing differs from the baseline. |
|
|
357
|
+
| `reverted` | `"Reverted"` | Announced when a change is reverted. |
|
|
358
|
+
| `revert` | `"Revert"` | The preview's revert button. |
|
|
359
|
+
| `revertTitle` | `"Revert this change (R)"` | Its tooltip, for a one-line change. |
|
|
360
|
+
| `revertLinesTitle` | `"Revert this change (lines {first}–{last}) (R)"` | Its tooltip, for a change over lines `{first}` to `{last}`. |
|
|
361
|
+
| `revertLineAndRemovedTitle` | `"Revert this change (line {line} and the removed lines) (R)"` | Its tooltip, for a changed line with removed lines. |
|
|
362
|
+
| `closePreview` | `"Close change preview"` | The preview's close button. |
|
|
363
|
+
| `before` | `"Before"` | The preview's column of the baseline's lines. |
|
|
364
|
+
| `current` | `"Current"` | The preview's column of the current lines. |
|
|
365
|
+
| `fold` | `"Fold line {line}"` | The chevron of an open range. |
|
|
366
|
+
| `unfold` | `"Unfold lines {first}–{last}"` | The chevron or chip of a closed fold. |
|
|
367
|
+
| `foldedChanges` | `"Folded lines have changes"` | A closed fold's line number when it hides changes or problems. |
|
|
368
|
+
| `foldedProblemOne` | `"hides a problem: {severity}"` | After a closed fold's chip label when it hides one problem; `{severity}` names it. |
|
|
369
|
+
| `foldedProblemOther` | `"hides {count} problems, the most serious: {severity}"` | After a closed fold's chip label when it hides `{count}` problems; `{severity}` names the most serious of them. |
|
|
370
|
+
| `foldedLines` | `"Folded lines {first}–{last}"` | Announced when the range of lines `{first}` to `{last}` folds. |
|
|
371
|
+
| `unfoldedLines` | `"Unfolded lines {first}–{last}"` | Announced when the fold of lines `{first}` to `{last}` opens. |
|
|
372
|
+
| `foldedRanges` | `"Folded {count} ranges"` | Announced when `{count}` ranges (two or more) fold at once. |
|
|
373
|
+
| `unfoldedRanges` | `"Unfolded {count} ranges"` | Announced when `{count}` folds (two or more) open at once. |
|
|
374
|
+
| `nothingToFold` | `"Nothing to fold"` | Announced when a fold key (`Ctrl+Shift+[`, `Ctrl+K Ctrl+0`) finds nothing to fold. |
|
|
375
|
+
| `nothingToUnfold` | `"Nothing to unfold"` | Announced when an unfold key (`Ctrl+Shift+]`, `Ctrl+K Ctrl+J`) finds nothing to open. |
|
|
376
|
+
| `required` | `"required"` | The hover card's mark of a required key. |
|
|
377
|
+
| `deprecated` | `"deprecated"` | The hover card's mark of a deprecated key. |
|
|
378
|
+
| `defaultValue` | `"Default"` | The hover card's default row. |
|
|
379
|
+
| `examples` | `"Examples"` | The hover card's examples row. |
|
|
380
|
+
| `oneOf` | `"One of"` | The hover card's row listing the titles of the options (`oneOf`, `anyOf`) a field's object may take, while none matches it yet. |
|
|
381
|
+
| `documentation` | `"Documentation"` | The hover card's link to the schema's documentation. |
|
|
382
|
+
| `hoverFocused` | `"In the docs: arrows, Page Up, Page Down, Home and End scroll them. Escape returns to the text."` | Announced when a second `Ctrl+K Ctrl+I` moves the focus into the hover card, to scroll it. |
|
|
383
|
+
| `hoverLabel` | `"About {key}"` | The focused hover card's accessible name: the `{key}` it documents. |
|
|
384
|
+
| `problemTipLabel` | `"Problems here"` | The problem tip's accessible name while it has the focus (a second `Ctrl+K Ctrl+I`). |
|
|
385
|
+
| `openDocs` | `"Open docs ↗ (Alt+Enter)"` | The link under a host problem's message. |
|
|
386
|
+
| `openDocsTouch` | `"Open docs ↗"` | `openDocs` on a touch screen, which has no keys to name. |
|
|
387
|
+
| `openDocsLabel` | `"{link}: {message}"` | A problem's docs link as a screen reader names it, told apart from the others in a tip: its `{link}` text (`openDocs`) and its problem's `{message}`. |
|
|
388
|
+
| `error` | `"Error"` | An error, as a screen reader hears it. |
|
|
389
|
+
| `warning` | `"Warning"` | A warning, as a screen reader hears it. |
|
|
390
|
+
| `info` | `"Info"` | An info, as a screen reader hears it. |
|
|
391
|
+
| `hint` | `"Hint"` | A hint, as a screen reader hears it. |
|
|
392
|
+
| `problemSource` | `" from {source}"` | Who reported a host problem: the `{source}` of the problem texts below (empty for the editor's own problems). |
|
|
393
|
+
| `problem` | `"{severity}{source}: {message}"` | A problem at the caret, for screen readers. |
|
|
394
|
+
| `problemPosition` | `"{severity} {position} of {total}{source}: {message}"` | Announced on `F8`: problem `{position}` of `{total}`. |
|
|
395
|
+
| `walkNoProblems` | `"No problems"` | Announced on `F8` when there are no problems. |
|
|
396
|
+
| `problemCode` | `" Code {code}."` | After a problem's text for screen readers: its `{code}` (from the host). |
|
|
397
|
+
| `problemDocs` | `" Documentation: {url} (Alt+Enter opens it)."` | After a problem's text (or the hover card's docs) for screen readers: its documentation's `{url}`, and the key that opens it. |
|
|
398
|
+
| `problemMarker` | `"{language} {severity}{source} on line {line}: {message}"` | An underlined problem's accessible name. |
|
|
399
|
+
| `protectedNote` | `"{label}: {message}"` | What protected text at the caret is, for screen readers: its `{label}` and `{message}`. |
|
|
400
|
+
| `sourceLabel` | `"{language} source"` | The text area. |
|
|
401
|
+
| `suggestionsLabel` | `"{language} suggestions"` | The suggestions list. |
|
|
402
|
+
| `problemsLabel` | `"Inline {language} diagnostics"` | The layer of underlined problems. |
|
|
403
|
+
| `editorLabel` | `"{language} editor"` | The editor's frame. |
|
|
404
|
+
| `readOnlyEditor` | `"Cannot edit in a read-only editor"` | Said, and shown at the caret, when typing in a read-only editor. |
|
|
405
|
+
| `readOnlyEditorReason` | `"Cannot edit in a read-only editor: {reason}"` | The same, for an editor the host said why it is read-only (`readOnlyReason`): `{reason}`. |
|
|
406
|
+
| `readOnlyField` | `"This field is read-only"` | Why a field is read-only when neither the schema nor the host says. |
|
|
407
|
+
| `readOnlyText` | `"This text is read-only"` | Why text in a read-only range the host gave cannot change. |
|
|
408
|
+
| `holdsReadOnly` | `"Holds a read-only field"` | Why renaming or moving the key above a read-only field is refused, when nothing says why the field is read-only. |
|
|
409
|
+
| `holdsReadOnlyReason` | `"Holds a read-only field: {reason}"` | The same, for a field the schema says why is read-only (`x-readonly-reason`): `{reason}`. |
|
|
410
|
+
| `saveRefused` | `"{pointer} is read-only and this change would alter it"` | A save refused because it would change a read-only value. |
|
|
411
|
+
| `saveWaits` | `"Not saved: {pointer} is read-only, and it can be checked only once the text is valid"` | A save waiting for the text to be valid: the language cannot say where the read-only field at `{pointer}` is written, so its value is checked only in a text that parses. |
|
|
412
|
+
| `saveHeld` | `"Not saved: the read-only field {pointer} no longer reads as the host gave it{reason}; put it back as it was to save"` | A save waiting because the read-only field at `{pointer}` no longer reads as the host gave it, held where the editor cannot tell why; `{reason}` is the `saveHeldReason` text when the schema says why the field is read-only (`x-readonly-reason`), else empty. The texts after it name each cause a hold records, with the same placeholders. |
|
|
413
|
+
| `saveHeldDuplicate` | `"Not saved: the read-only field {pointer} is written twice, and the other copy is read in its place{reason}; remove the copy to save"` | The same, because its key or a block holding it is written twice, and the other copy is read in its place. |
|
|
414
|
+
| `saveHeldRenamed` | `"Not saved: a key holding the read-only field {pointer} was renamed{reason}; give the key its old name back to save"` | The same, because a key on its path was renamed (by an edit or an undo). |
|
|
415
|
+
| `saveHeldMoved` | `"Not saved: the read-only field {pointer} moved under another parent{reason}; move it back to save"` | The same, because its text now sits under another parent. |
|
|
416
|
+
| `saveHeldListItem` | `"Not saved: the read-only field {pointer} is now another item of its list, because items were added, removed or moved before it{reason}; put the items back in order to save"` | The same, for a list item whose place in its list now holds another item (items were added, removed or moved before it). |
|
|
417
|
+
| `saveHeldCommented` | `"Not saved: the read-only field {pointer} is commented out{reason}; remove the comment mark to save"` | The same, because its line is commented out. |
|
|
418
|
+
| `saveHeldRemoved` | `"Not saved: the read-only field {pointer} is no longer in the text{reason}; write it back as the host gave it to save"` | The same, because the text no longer has it. |
|
|
419
|
+
| `saveHeldAdded` | `"Not saved: the read-only field {pointer} now reads text that was added into it or beside it{reason}; remove that text to save"` | The same, because text was added into it or beside it (a key in its block, a line taken into its value). |
|
|
420
|
+
| `saveHeldSpanless` | `"Not saved: the read-only field {pointer} now reads another value than the host gave{reason}; put its value back as it was to save"` | The same, in a language that cannot say where the field is written: its value reads otherwise. |
|
|
421
|
+
| `saveHeldRange` | `"Not saved: the read-only text the host gave no longer reads as {pointer}{reason}; put that text back where it was to save"` | The same, for a field in a read-only range the host gave: the range's text no longer reads as that field. |
|
|
422
|
+
| `saveHeldBeforeLock` | `"Not saved: {pointer} was changed before the host made it read-only{reason}; put it back as the host gave it to save"` | The same, for a field the host made read-only after it was changed: the text reads it otherwise than the host's text does. |
|
|
423
|
+
| `saveHeldReason` | `" ({reason})"` | What a `save_held…` text says of why the field is read-only, when the schema says (`x-readonly-reason`): its `{reason}`. |
|
|
424
|
+
| `saveHeldPlaceholder` | `"Not saved: {pointer} now reads other text beside its secret placeholder; remove that text so the placeholder stands alone to save"` | A save waiting because the secret field at `{pointer}` now reads text beside a placeholder the host gave as its whole value (an edit beside it, or an undo, made the parse read them together). |
|
|
425
|
+
| `readOnlyLabel` | `"Read-only"` | The gutter lock's label, before the reason. |
|
|
426
|
+
| `secretLabel` | `"Secret placeholder"` | The gutter key's label, before the hint. |
|
|
427
|
+
| `secretHint` | `"Keeps the current secret unless you replace it"` | The hover text of a secret placeholder, unless the host gives one. |
|
|
428
|
+
| `secretValue` | `"the secret value"` | What a schema problem says instead of a secret field's value. |
|
|
429
|
+
| `secretInside` | `"…"` | What a schema problem writes in place of each secret inside a value it quotes (a list or map holding one). |
|
|
430
|
+
| `unknownPlaceholder` | `"{pointer}: unknown secret placeholder; it stands for no current secret, so write the new value instead"` | A placeholder the host did not give, in a secret field. |
|
|
431
|
+
| `movedPlaceholder` | `"{pointer}: this placeholder stands for the secret of {owner}, not this field's; here it is plain text"` | One of the host's placeholders outside the field it stands in. |
|
|
432
|
+
| `foreignPlaceholder` | `"This placeholder stands for a secret of {source}, not of this document; here it is plain text"` | One of another document's placeholders (in a documents view), `{source}` its file name. |
|
|
433
|
+
| `extraPlaceholder` | `"{pointer}: this placeholder is in this field already; another copy of it is plain text"` | One of the host's placeholders written in its own field more often than the host gave it there: a copy of it. |
|
|
434
|
+
| `placeholderInComment` | `"This placeholder stands for the secret of {owner}; in a comment it is plain text"` | One of the host's field placeholders written in a comment. |
|
|
435
|
+
| `commentPlaceholder` | `"{pointer}: this placeholder stands for a secret in a comment, not this field's; here it is plain text"` | A placeholder the host wrote in a comment, in a field. |
|
|
436
|
+
| `gluedPlaceholder` | `"{pointer}: a secret placeholder stands for the whole secret, so nothing can be written beside it: replace it whole to write a new value"` | Text written beside a placeholder the host gave as a field's whole value: the edit refused, the field flagged, a save waiting. |
|
|
437
|
+
| `envReference` | `"Read the secret from an environment variable"` | The detail of the `${…}` reference suggestion. |
|
|
438
|
+
| `fileReference` | `"Read the secret from a file"` | The detail of the `file:` reference suggestion. |
|
|
439
|
+
| `otherReference` | `"A reference starting with {prefix}"` | The detail of another reference suggestion. |
|
|
440
|
+
| `referenceType` | `"reference"` | The type column of a reference suggestion. |
|
|
441
|
+
| `closesTag` | `"Closes <{name}>"` | The detail of the end tag XML suggests. |
|
|
442
|
+
| `endTag` | `"end tag"` | Its type column. |
|
|
443
|
+
| `noSuggestions` | `"No suggestions"` | Said when Ctrl+Space finds nothing to offer, and when typing empties a list opened with Ctrl+Space or moved in; a list that opened by itself closes silently. |
|
|
444
|
+
| `keyNotAllowed` | `"\"{key}\" is not allowed here"` | A key the schema does not allow (`{key}`); its object's pointer goes before it (`/web: `), as before every schema problem but at the root. |
|
|
445
|
+
| `textNotAllowed` | `"text is not allowed here, only elements"` | Text in an element the schema wants elements in (XML); the element's pointer goes before it. |
|
|
446
|
+
| `keyDeprecated` | `"{pointer}: \"{key}\" is deprecated"` | A deprecated key. |
|
|
447
|
+
| `keyDeprecatedInstead` | `"{pointer}: \"{key}\" is deprecated. {message}"` | A deprecated key whose schema says what to use instead. |
|
|
448
|
+
| `notOneOf` | `"{value} is not one of {allowed}"` | A value not among the allowed ones. |
|
|
449
|
+
| `wrongType` | `"{value} is not of type {types}"` | A value of none of the accepted types. |
|
|
450
|
+
| `notFormat` | `"{value} is not a valid {format}"` | A value out of its `format` (checked up to draft-07): `{format}` is its name, quoted. |
|
|
451
|
+
| `noItemContained` | `"no item of the list matches its \"contains\" schema"` | A list with no item its `contains` schema allows. |
|
|
452
|
+
| `tooFewContained` | `"fewer than {limit} items of the list match its \"contains\" schema"` | A list with fewer items its `contains` schema allows than its `minContains` (`{limit}`). |
|
|
453
|
+
| `tooManyContained` | `"more than {limit} items of the list match its \"contains\" schema"` | A list with more items its `contains` schema allows than its `maxContains` (`{limit}`). |
|
|
454
|
+
| `tooFewItems` | `"the number of items must be at least {limit}, and is {count}"` | A list with fewer items (`{count}`) than its `minItems` (`{limit}`). |
|
|
455
|
+
| `tooManyItems` | `"the number of items must be at most {limit}, and is {count}"` | A list with more items (`{count}`) than its `maxItems` (`{limit}`). |
|
|
456
|
+
| `tooFewKeys` | `"the number of keys must be at least {limit}, and is {count}"` | An object with fewer keys (`{count}`) than its `minProperties` (`{limit}`). |
|
|
457
|
+
| `tooManyKeys` | `"the number of keys must be at most {limit}, and is {count}"` | An object with more keys (`{count}`) than its `maxProperties` (`{limit}`). |
|
|
458
|
+
| `repeatedItem` | `"the list holds {item} more than once: each item must differ"` | A list holding an item (`{item}`, as JSON) more than once where its `uniqueItems` wants each item different. |
|
|
459
|
+
| `mustNotMatch` | `"{value} is not allowed here"` | A value its `not` schema (`{schema}`, as JSON) matches, where no plainer words below say why. |
|
|
460
|
+
| `mustNotMatchPattern` | `"{value} must not match the pattern {pattern}"` | A text matching the pattern its `not` schema refuses (`not: {pattern: …}`): the pattern (`{pattern}`), quoted as JSON. |
|
|
461
|
+
| `mustNotBeType` | `"{value} must not be of type {types}"` | A value of a type its `not` schema refuses (`not: {type: …}`): the types (`{types}`), each quoted, joined by `, `. |
|
|
462
|
+
| `mustNotBe` | `"{value} is one of the values not allowed here: {values}"` | A value its `not` schema refuses among others by name (`not: {enum: […]}` of two or more values): the refused values (`{values}`), as JSON, joined by `, `. One refused value (`not: {const: …}`) is told by `mustNotMatch`. |
|
|
463
|
+
| `mustNotHave` | `"{keys} must not be set here"` | An object holding keys its `not` schema refuses one by one (`not: {anyOf: [{required: [a]}, {required: [b]}]}`): the ones it holds (`{keys}`), each quoted, joined by `, `; the object is `{value}`. |
|
|
464
|
+
| `keysUsedTogether` | `"{key} can't be used together with {other}"` | An object holding both keys its `not` schema keeps apart (`not: {required: [a, b]}`, or a key's dependent schema's `not`): the first (`{key}`) and the other (`{other}`), each quoted. |
|
|
465
|
+
| `keysAllUsedTogether` | `"{keys} can't all be used together"` | An object holding all of three or more keys its `not` schema keeps apart (`not: {required: [a, b, c]}`): the keys (`{keys}`), each quoted, joined by `, `. |
|
|
466
|
+
| `noOptionMatches` | `"matches none of the {keyword} options: {reasons}"` | A value that matches none of a schema's options (`{keyword}`: `oneOf` or `anyOf`), with why each fails (`{reasons}`, each worded by `optionNeeds`, `optionRefuses` or `optionProblem`, joined by `; `). |
|
|
467
|
+
| `severalOptionsMatch` | `"matches more than one of the oneOf options ({options}); only one may match"` | A value that matches more than one of a `oneOf`'s options (`{options}`, their names joined by `, `). |
|
|
468
|
+
| `optionNeeds` | `"{option} needs \"{key}\""` | An option (`{option}`) that needs a key the value does not have. |
|
|
469
|
+
| `optionRefuses` | `"{option} does not allow \"{key}\""` | An option (`{option}`) that does not allow a key the value has. |
|
|
470
|
+
| `optionProblem` | `"{option}: {problem}"` | An option (`{option}`) and another problem it has with the value. |
|
|
471
|
+
| `optionNumber` | `"option {number}"` | The name of an option with no title or description (`{number}`, from 1). |
|
|
472
|
+
| `invalidSchema` | `"Invalid JSON Schema: {error}"` | A schema that does not compile. |
|
|
473
|
+
| `emptySchema` | `"Invalid JSON Schema: the schema text is empty"` | A schema whose text is empty, or only spaces and line breaks. |
|
|
474
|
+
| `invalidPlaceholder` | `"secrets.placeholder: {error}"` | A secret placeholder pattern the editor cannot use (it does not compile, or matches empty text): no token is taken for a placeholder. |
|
|
475
|
+
| `problemAtPath` | `"{path}: {message}"` | A host's problem with a field the editor cannot find in the text, listed with the field's path. |
|
|
476
|
+
| `hostCannotKeep` | `"{pointer}: {host} cannot keep this value exactly, as it reads back differently: change it, or edit it as {host}, to save"` | A value the host's language reads back differently (Edit-as). |
|
|
477
|
+
| `editCannotShow` | `"{pointer}: {edit} cannot show this value exactly; editing it here may change it"` | A value the edited language cannot show exactly (Edit-as). |
|
|
478
|
+
| `notSaved` | `"Not saved as {host}: {error}"` | An edit the host's language cannot save (Edit-as). |
|
|
479
|
+
| `noNull` | `"{host} has no null value: give it a value or remove it to save (at {pointer})"` | A null the host's language cannot write (Edit-as). |
|
|
480
|
+
| `noNonFinite` | `"{host} has no infinity or NaN: write a finite number or remove it to save (at {pointer})"` | An infinity or NaN the host's language has no number for (Edit-as). |
|
|
481
|
+
| `cannotSwitch` | `"Cannot switch to {edit} yet: {error}"` | An Edit-as switch waiting until the document converts. |
|
|
482
|
+
| `switchRefused` | `"Cannot edit as {edit}: {error}"` | An Edit-as switch refused: the host's language or the other one cannot write documents. |
|
|
483
|
+
| `mixedContent` | `"{pointer}: text beside child elements cannot be shown in another language"` | XML text beside child elements, which no other language can show (Edit-as). |
|
|
484
|
+
| `tabList` | `"Open files"` | The tab list's accessible name, unless the host gives one. |
|
|
485
|
+
| `noDocuments` | `"No open files"` | Shown in place of an editor while no document is open. |
|
|
486
|
+
| `closeTab` | `"Close {name}"` | A tab's close button. |
|
|
487
|
+
| `closeTabTitle` | `"Close (Delete)"` | Its tooltip. |
|
|
488
|
+
| `addDocument` | `"New file"` | The "+" button after the tabs (with `onAdd`): its accessible name and tooltip. |
|
|
489
|
+
| `unsaved` | `"unsaved changes"` | The dirty dot's tooltip, and what a tab's accessible name adds for it. |
|
|
490
|
+
| `readOnlyTab` | `"read-only"` | What a read-only document's tab adds to its accessible name. |
|
|
491
|
+
| `readOnlyTabTitle` | `"{name}\nRead-only: {reason}"` | The tooltip of a read-only document's tab with a reason (`readOnlyReason`): its file `{name}` and the `{reason}`. |
|
|
492
|
+
|
|
493
|
+
</details>
|
|
494
|
+
|
|
495
|
+
<!-- strings:end -->
|
|
496
|
+
|
|
497
|
+
### `update(options)`
|
|
498
|
+
|
|
499
|
+
`editor.update(options)` changes a mounted editor, live (the caret, undo
|
|
500
|
+
history, scroll and folds stay). It takes the constructor's options, any of
|
|
501
|
+
them, and is the one way to change one:
|
|
502
|
+
|
|
503
|
+
```ts
|
|
504
|
+
editor.update({ readOnly: true, theme: "nord" });
|
|
505
|
+
editor.update({ value: loaded, baseline: loaded }); // a file the host loaded
|
|
506
|
+
editor.update({ hostDiagnostics: problems, onSave: null });
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
<details>
|
|
510
|
+
<summary>How update treats left-out keys, null, settings, a new value and fixed options</summary>
|
|
511
|
+
|
|
512
|
+
- A key left out, or set to `undefined`, stays as it is.
|
|
513
|
+
- A callback given where there was none reporting a state (`onEditAsChange`,
|
|
514
|
+
`onSyncChange`, `onProblems`, `onDirtyChange`, `onChangeSummary`) hears the
|
|
515
|
+
current one at once, as it would have on mount (a `ConfigDocuments` tells
|
|
516
|
+
it of each document).
|
|
517
|
+
- `null` removes a callback (`onSave: null` gives `Ctrl+S` back to the
|
|
518
|
+
browser), clears `hostDiagnostics`, `readOnlyPaths` and `readOnlyRanges`,
|
|
519
|
+
turns `editAs` and `readOnly` off, and returns a setting to its default.
|
|
520
|
+
- Settings merge key by key, `strings` text by text and `colors` token by
|
|
521
|
+
token, as the settings do: a text or token set to `undefined` stays, one
|
|
522
|
+
set to `null` returns to its default (`colors: null` clears them all).
|
|
523
|
+
- A new `value` replaces the document as a host update, whatever it is (a
|
|
524
|
+
file switched to, a discard, a reset); a `value` that is the document
|
|
525
|
+
already changes nothing. The caret stays on the same text when possible.
|
|
526
|
+
`readOnlyRanges` and host `range`s given with it are in the new document,
|
|
527
|
+
and lock exactly what they name there: give ranges with a `value` only
|
|
528
|
+
when you worked them out for that text (the framework components give a
|
|
529
|
+
list only when it changed). Without `readOnlyRanges`, the ones you gave
|
|
530
|
+
last are carried into the new text by a diff, as after `replaceValue`:
|
|
531
|
+
where the diff cannot tell where a lock went, the whole changed lines
|
|
532
|
+
around it stay locked until you give ranges again. `readOnlyPaths` do not
|
|
533
|
+
depend on places in the text.
|
|
534
|
+
The text `onChange` gave last, given while the editor still held a newer
|
|
535
|
+
edit (one edited as another language, waiting out the typing pause, that
|
|
536
|
+
the update first sends to `onChange`), is older than what was typed: it
|
|
537
|
+
keeps the document. For a host that hands every `onChange` text back, see
|
|
538
|
+
[Hosts that echo](#hosts-that-echo).
|
|
539
|
+
- `readOnlyRanges` equal to the ones given last (the same JSON), given again
|
|
540
|
+
with no new text (a host passing all its options again, with the `value`
|
|
541
|
+
`onChange` gave), stay where the editor moved them as the user typed: they
|
|
542
|
+
are not read again at the places they name in the edited text. Ranges that
|
|
543
|
+
differ, or come with a new text or `rangesFor`, or the same ones after a
|
|
544
|
+
text of your own replaced the document (`replaceValue`), are read in that
|
|
545
|
+
text. Ranges that name places the text they come with lacks (a line or
|
|
546
|
+
index past its end, a column past its line's end) but fit the text the last
|
|
547
|
+
ones came with are read in that one and moved to the document (a
|
|
548
|
+
framework's render listing a newer text with ranges worked out on the one
|
|
549
|
+
it rendered before).
|
|
550
|
+
While a save is held, the document has moved on by edits you have not
|
|
551
|
+
heard yet; ranges given then are moved through those edits. A range
|
|
552
|
+
whose text one of those edits changed before the lock locks nothing, and
|
|
553
|
+
the save waits with a "Not saved: …" reason until that text is back.
|
|
554
|
+
- `rangesFor` names the text an update's (or the constructor's)
|
|
555
|
+
`readOnlyRanges` and host `range`s were worked out for, when it is not the document (a check of a text the
|
|
556
|
+
user has typed past since): they are checked in it and moved to the
|
|
557
|
+
document, a range around an edit growing over it (a lock never lets a
|
|
558
|
+
locked character be edited). Ranges given with a `value` are in that
|
|
559
|
+
`value`, applied or an echo.
|
|
560
|
+
- `language`, `schema`, `fileName`, `className`, `secrets` and `echoes` are what the
|
|
561
|
+
editor is built from: they throw (`"language cannot change on a mounted
|
|
562
|
+
ConfigEditor …"`); create a new editor to change them. The value one was
|
|
563
|
+
built with, given again (the same `schema` text, the same `secrets`
|
|
564
|
+
object; for `language`, the editor's own under any spelling), changes
|
|
565
|
+
nothing, as a framework passing all its props again does; an option left
|
|
566
|
+
out was built with its default (`null`, `echoes: false`, `className: ""`,
|
|
567
|
+
the `fileName` the toolbar shows). TypeScript types
|
|
568
|
+
them `never` in `EditorUpdate`.
|
|
569
|
+
- Every key is checked before any applies: a wrong value throws and changes
|
|
570
|
+
nothing.
|
|
571
|
+
|
|
572
|
+
</details>
|
|
573
|
+
|
|
574
|
+
#### Hosts that echo
|
|
575
|
+
|
|
576
|
+
A host that only saves what `onChange` gives (`onChange: save`, as in the
|
|
577
|
+
[Quick start](#quick-start)) needs nothing more: every `value` it passes to
|
|
578
|
+
`update` applies. A host that hands every `onChange` text back through
|
|
579
|
+
`update({ value })` (a store that re-renders after a delay, a fetch per
|
|
580
|
+
edit) may do it late, after the user typed on, and in any order. Applying
|
|
581
|
+
such an echo would roll the document back, so tell the editor with
|
|
582
|
+
`echoes: true`:
|
|
583
|
+
|
|
584
|
+
```ts
|
|
585
|
+
const editor = new ConfigEditor(element, {
|
|
586
|
+
value: store.text,
|
|
587
|
+
echoes: true,
|
|
588
|
+
onChange: (text) => store.save(text), // the store calls editor.update({ value }) later
|
|
589
|
+
});
|
|
590
|
+
```
|
|
591
|
+
|
|
592
|
+
Then a `value` that `onChange` gave and that has not come back yet is its
|
|
593
|
+
echo and keeps the document, in any order and however late: nothing typed
|
|
594
|
+
is lost. Each text sent is kept (a short print of it, not the text) until
|
|
595
|
+
its echo comes or a text of yours replaces the document; never by time. An echo the store wrote another way (without the byte order mark,
|
|
596
|
+
with LF line breaks) is still the echo, and the document keeps its own.
|
|
597
|
+
Ranges given with an echo (`readOnlyRanges`, host `range`s) are in
|
|
598
|
+
the echoed text: they are moved to the document. The text you gave last,
|
|
599
|
+
given again, is no news either: a render for another prop passes your
|
|
600
|
+
store's text again while it is still behind the typing (reset to it with
|
|
601
|
+
`replaceValue`). Any other `value` is yours and applies (a discard to the
|
|
602
|
+
text the editor was created with, once your store took a later one). The texts `onChange` gave before it belong to the
|
|
603
|
+
text it replaced (another file, a discarded draft): they are yours from
|
|
604
|
+
then on, so going back to one (a file switched back to) applies. So once
|
|
605
|
+
you give a text of your own, drop the answers still to come for the texts
|
|
606
|
+
before it, or hand them to the file they belong to; a host that cannot
|
|
607
|
+
(every answer handed back, whatever happened since) resets with
|
|
608
|
+
`replaceValue` instead. When an echo
|
|
609
|
+
leaves your store holding an older text and nothing still on its way brings
|
|
610
|
+
it back, `onChange` gives it the document again. A store that takes
|
|
611
|
+
several texts in one render passes only the last, so the echo that would
|
|
612
|
+
bring it back may never be seen: if the store is still on an older text
|
|
613
|
+
250 ms after such an echo, `onChange` gives it the document again then.
|
|
614
|
+
That pause is the one place time enters, and only without revisions: the
|
|
615
|
+
editor cannot tell an echo lost in a render from one still on its way by the
|
|
616
|
+
texts alone.
|
|
617
|
+
|
|
618
|
+
An editor a framework creates again (a new `language` or `fileName`) takes
|
|
619
|
+
over the echoes of the one it replaces: pass the old editor's `channel` as
|
|
620
|
+
the new one's `channel` option; given no `readOnlyRanges`, it also holds the
|
|
621
|
+
old editor's ranges where they are now. The framework components do it for you.
|
|
622
|
+
|
|
623
|
+
With revisions there is no pause. `onChange(text, revision)` gives each text
|
|
624
|
+
a revision; store it beside the text, keep only the newest revision you were
|
|
625
|
+
given (never go back to an older one), and pass it back:
|
|
626
|
+
`update({ value, valueRevision })`. The echo is then matched exactly: that
|
|
627
|
+
revision and every earlier one are confirmed, an older value given back means
|
|
628
|
+
a newer one is still on its way, and nothing is sent again. Give a text of
|
|
629
|
+
your own without `valueRevision`. So the editor counts every text it gave
|
|
630
|
+
as on its way until you pass back its revision or a later one, and never
|
|
631
|
+
sends it again by itself: a store that loses one (a save that failed, a
|
|
632
|
+
render that dropped it) must send it again, for instance the newest text
|
|
633
|
+
`onChange` gave with its revision. To go back to a text
|
|
634
|
+
`onChange` gave that may still be on its way (a discard to what you saved, a
|
|
635
|
+
revert), or to reset while the echoes of what was typed are still to come,
|
|
636
|
+
call `replaceValue(text)`: it always applies, and the echoes on their way
|
|
637
|
+
are still told apart. Your store then takes that text, late if it likes:
|
|
638
|
+
given back after what is typed next, it is the reset's echo and keeps the
|
|
639
|
+
typing, also for a reset to the text you gave last (a discard to the file
|
|
640
|
+
as loaded). A reset to the document as it is changes nothing (a second
|
|
641
|
+
Discard): your store holds that text once. `replaceValue` does not report the text, so set it in your store
|
|
642
|
+
yourself. A framework component's `setValue` reports it through `onChange`
|
|
643
|
+
instead: there, reset with `setValue` or by setting your state, not both at
|
|
644
|
+
once (without `valueRevision`, the late echo of the report can undo what is
|
|
645
|
+
typed next). The `readOnlyRanges` you gave go
|
|
646
|
+
with the text they cover into the reset's text, carried afresh from the text
|
|
647
|
+
you gave them for by a line and character diff: a lock whose text is kept
|
|
648
|
+
stays on it, and one whose text changed in place grows over what replaced
|
|
649
|
+
it. Where the diff cannot tell where a lock went (its lines rewritten, a
|
|
650
|
+
text with nothing of it left), the whole changed lines around it are
|
|
651
|
+
locked: never a guess, and no lock is dropped. They stay locked until you
|
|
652
|
+
give ranges again: the ranges you give next, the same ones too, are read in
|
|
653
|
+
the text they come with, and lock exactly what they name there. Ranges that
|
|
654
|
+
name places past that text's end but fit the text the last ones came with
|
|
655
|
+
before the reset (a host rendering the ranges it had) are read in that one
|
|
656
|
+
and moved to the document. The promise is
|
|
657
|
+
yours to keep: a host that hands back only some texts (the latest of
|
|
658
|
+
several) leaves the others counted as echoes (every text sent is
|
|
659
|
+
remembered until its echo comes or a text of your own replaces the
|
|
660
|
+
document), so set those with `replaceValue` too.
|
|
661
|
+
|
|
662
|
+
### Instance members
|
|
663
|
+
|
|
664
|
+
`ConfigEditor` is an `EditorView`, the interface a document's editor in a
|
|
665
|
+
[`ConfigDocuments`](#several-documents) (`view.editor(id)`) implements too:
|
|
666
|
+
|
|
667
|
+
| `EditorView` member | Description |
|
|
668
|
+
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
669
|
+
| `value` (getter) | The current document, in `language`, including an edit made in `editAs` that is still waiting out the typing pause (it is sent to `onChange` first). Still readable after `destroy()`. |
|
|
670
|
+
| `text` (getter) | The text on screen (closed folds' lines included): in the `editAs` language while editing as another one. `rangeOf` and `pathAt` index into it; `value` is the document in `language`. |
|
|
671
|
+
| `isDirty` (getter) | Whether the document differs from the baseline. |
|
|
672
|
+
| `currentPath` (getter) | The path of what the caret is on; see [Paths](#paths). |
|
|
673
|
+
| `foldedLines` (getter) | The folded blocks, one-based `{ startLine, endLine }[]`: the line that stays visible and the last hidden one. |
|
|
674
|
+
| `settings` (getter) | The settings in effect, every key set; see [Settings](#settings). |
|
|
675
|
+
| `reveal(path)`, `revealRange(range)`, `rangeOf(path)`, `pathAt(index)` | Paths and positions; see [Paths](#paths). |
|
|
676
|
+
| `fold(path)`, `unfold(path)`, `foldAll()`, `unfoldAll()` | Fold the block a field's key opens / open the folds around a field (`false` when there was nothing to do); fold or open everything. See [Folding](#folding). |
|
|
677
|
+
| `focus()` | Focus the editor, keeping its selection. |
|
|
678
|
+
| `save()` | Save as `Ctrl+S` does (calls `onSave`); `false` when nothing was sent (no `onSave`, text that does not parse, or an `editAs` edit that cannot convert back yet). |
|
|
679
|
+
| `unifiedDiff(context?)` | The `diff -u` of the baseline against the document, with `context` unchanged lines around each change (default 3); `""` when they are the same. Its lines end with LF. |
|
|
680
|
+
|
|
681
|
+
`ConfigEditor` adds:
|
|
682
|
+
|
|
683
|
+
| Member | Description |
|
|
684
|
+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
685
|
+
| `update(options)` | Change the editor live; see [`update`](#updateoptions). |
|
|
686
|
+
| `replaceValue(text)` | Replace the document with a text of your own, whatever it is: with `echoes`, `update({ value })` takes a text `onChange` gave that has not come back yet for its echo and keeps the document; this never does (a revert to such a text). The caret stays on the same text when possible, and the `readOnlyRanges` on the text they cover; `onChange` does not hear it. Returns whether it replaced the document (`false` for the text it holds already). |
|
|
687
|
+
| `destroy()` | Unmount. An edit still converting (while editing as another language) is sent to `onChange` first. Safe to call inside any callback (`onChange`, `onSave`, …). |
|
|
688
|
+
| `free()` | Release the WebAssembly object after `destroy()`. Optional; the garbage collector does it too. An editor stays on the page until `destroy()`, whether or not you keep a reference to it. Call `destroy()` first: after `free()` the instance cannot be used at all (wasm-bindgen's own method). Inside a callback it frees once the callback returns. |
|
|
689
|
+
|
|
690
|
+
An exception thrown by a callback is logged to the console and does not
|
|
691
|
+
break the editor.
|
|
692
|
+
|
|
693
|
+
### Host diagnostics
|
|
694
|
+
|
|
695
|
+
When the host checks the document itself (a service, a build step), show its
|
|
696
|
+
problems with the editor's own:
|
|
697
|
+
|
|
698
|
+
```ts
|
|
699
|
+
editor.update({
|
|
700
|
+
hostDiagnostics: [
|
|
701
|
+
{
|
|
702
|
+
path: "/web/listen",
|
|
703
|
+
severity: "error",
|
|
704
|
+
message: "port 80 is taken",
|
|
705
|
+
code: "E_PORT",
|
|
706
|
+
source: "validator",
|
|
707
|
+
docsUrl: "https://example.com/docs/ports",
|
|
708
|
+
},
|
|
709
|
+
{
|
|
710
|
+
range: { startLine: 4, startColumn: 1, endColumn: 19 },
|
|
711
|
+
severity: "hint",
|
|
712
|
+
message: "consider TLS",
|
|
713
|
+
},
|
|
714
|
+
{ severity: "warning", message: "restart needed to apply" }, // the whole document
|
|
715
|
+
],
|
|
716
|
+
});
|
|
717
|
+
```
|
|
718
|
+
|
|
719
|
+
<details>
|
|
720
|
+
<summary>Paths and ranges, severities, F8 and hover, what throws, limits</summary>
|
|
721
|
+
|
|
722
|
+
- `path` (a JSON pointer or keys and indices) is marked where the field is
|
|
723
|
+
written and follows it through edits and `editAs`. `range` is in the
|
|
724
|
+
document (`value`, in `language`): string indices `{ start, end }` or
|
|
725
|
+
one-based `{ startLine, startColumn, endLine?, endColumn? }`, underlined on
|
|
726
|
+
every line it covers (up to 200; at most 200 underlines in all, the most
|
|
727
|
+
serious problems first, and the footer says when some were left out;
|
|
728
|
+
`F8` reaches every one). While editing as another language it
|
|
729
|
+
marks the field it starts in (its key when it starts on the key). With
|
|
730
|
+
neither, or when the field is missing, the problem shows in the footer,
|
|
731
|
+
after the field's path (`/web/listen: port 80 is taken`).
|
|
732
|
+
- A `range` with no end (`{ startLine, startColumn }`, no `endColumn` and
|
|
733
|
+
no `endLine` past `startLine`) is a point and never widened from the text
|
|
734
|
+
around it: on a secret placeholder (a token the `secrets` pattern
|
|
735
|
+
matches) it underlines the whole token, from any column inside it;
|
|
736
|
+
elsewhere one character, at a line's end the place just past it, on an
|
|
737
|
+
empty line its start.
|
|
738
|
+
- `severity` is `"error"` (default), `"warning"`, `"info"` or `"hint"`,
|
|
739
|
+
written so (`"ERROR"` throws); colors `error`, `warning`, `info` and
|
|
740
|
+
`hint` in `colors`. `message` is required and not empty.
|
|
741
|
+
- `F8` stops at them, the footer counts them, and the hover message adds
|
|
742
|
+
`source` (default `"host"`), `code` and "Open docs ↗": a click on the
|
|
743
|
+
message opens `docsUrl` (an `http:` or `https:` URL with a host), as `Alt+Enter`
|
|
744
|
+
does with the caret on the problem; screen readers hear the code and the
|
|
745
|
+
link with the problem.
|
|
746
|
+
- `path` and `range` are exclusive; a range past the text's end, ending
|
|
747
|
+
before it starts, `{ start }` without `end`, or a pointer without its
|
|
748
|
+
leading `/` throws. A range may give both styles (as `rangeOf` returns
|
|
749
|
+
it) when they name the same stretch, its indices in `value` or in the
|
|
750
|
+
text on screen (the editor's own `rangeOf`, whose lines end with LF: in a
|
|
751
|
+
CRLF file its indices alone name another stretch of `value`, so give its
|
|
752
|
+
range whole or its lines). `start` and `end` are string indices
|
|
753
|
+
(UTF-16 units, in `text`); `startColumn` and `endColumn`
|
|
754
|
+
count characters (code points, as problems' columns do): `😀` is two
|
|
755
|
+
indices and one column. A column past its line's end is read as the
|
|
756
|
+
line's end, with a console warning (the rest of the update applies).
|
|
757
|
+
- The editor lists and underlines at most 20 problems of each source (the
|
|
758
|
+
schema's, the secret placeholders'), and the footer says how many were
|
|
759
|
+
cut ("20+ errors · only the editor's first 20 are shown"); a problem with no place
|
|
760
|
+
(the whole document's) stays in the footer and `F8` reaches it.
|
|
761
|
+
- Where the host marks the same text as one of the editor's own problems
|
|
762
|
+
with the same message (with or without its JSON pointer), it shows once:
|
|
763
|
+
the more serious of the two, the host's when as serious (a host warning
|
|
764
|
+
repeating a schema error leaves the error);
|
|
765
|
+
a different message shows beside it. A new list replaces the previous one (`null` or
|
|
766
|
+
`[]` clears it); only the markers update. An invalid entry throws, naming
|
|
767
|
+
its index.
|
|
768
|
+
|
|
769
|
+
</details>
|
|
770
|
+
|
|
771
|
+
### Read-only fields
|
|
772
|
+
|
|
773
|
+
A field is read-only when the schema marks it `readOnly: true` (with its
|
|
774
|
+
reason in `x-readonly-reason`), or when the host names it:
|
|
775
|
+
|
|
776
|
+
```ts
|
|
777
|
+
const editor = new ConfigEditor(element, {
|
|
778
|
+
language: "yaml",
|
|
779
|
+
value,
|
|
780
|
+
schema, // {"properties": {"id": {"readOnly": true, "x-readonly-reason": "Assigned when created"}}}
|
|
781
|
+
readOnlyPaths: ["/limits"],
|
|
782
|
+
readOnlyRanges: [{ startLine: 1, startColumn: 1, endLine: 2, endColumn: 1 }],
|
|
783
|
+
});
|
|
784
|
+
editor.update({ readOnlyPaths: ["/limits", "/tls/cert"] }); // at runtime
|
|
785
|
+
```
|
|
786
|
+
|
|
787
|
+
<details>
|
|
788
|
+
<summary>How locks behave: refused edits, formatting, syntax errors, suggestions, Edit-as</summary>
|
|
789
|
+
|
|
790
|
+
- A lock in the gutter marks each locked line, the value is muted (color
|
|
791
|
+
token `locked`), and hovering it shows the reason.
|
|
792
|
+
- Locked text is each read-only value, its key and the keys holding it,
|
|
793
|
+
and each `readOnlyRanges` entry, found where the text last parsed and
|
|
794
|
+
followed through every edit by position. Typing, deleting, pasting,
|
|
795
|
+
cutting, completions, Replace, `Ctrl+/`, Revert, line commands and undo
|
|
796
|
+
that change that text or glue text onto a value are refused: the text stays, and a tooltip at the caret
|
|
797
|
+
says why. Replace All skips matches in read-only text and says how many.
|
|
798
|
+
- Everything else goes through: a new key beside a locked one whatever its
|
|
799
|
+
name, and also a second copy of a locked key or block, or a key added
|
|
800
|
+
past a locked block's end. While the document then reads a locked field
|
|
801
|
+
otherwise (a duplicate shadows it, it moved, its key was renamed, it was commented out),
|
|
802
|
+
nothing reaches you: `onChange` and `value` wait, and `save()` waits
|
|
803
|
+
(returns `false`, saying which field and what happened to it) until it
|
|
804
|
+
reads as given again.
|
|
805
|
+
- A field named in `readOnlyPaths` after the user changed it holds the
|
|
806
|
+
user's text, not yours: it locks nothing, every edit there goes through
|
|
807
|
+
(Backspace, undo, the line typed again), and `save()` waits with a
|
|
808
|
+
"Not saved: … was changed before the host made it read-only" reason. Once
|
|
809
|
+
it reads as your text gives it, it is locked.
|
|
810
|
+
- Whitespace, comments and punctuation around a locked field stay free
|
|
811
|
+
(also whitespace inside it, such as a space after `:`); in YAML the
|
|
812
|
+
lines inside a locked block keep their indent (it is structure). A syntax error anywhere
|
|
813
|
+
keeps every lock, also in a `value` that does not parse and for
|
|
814
|
+
`readOnlyPaths` given while the text does not parse.
|
|
815
|
+
- Suggestions leave read-only keys out (inside a read-only block they are
|
|
816
|
+
listed with the reason).
|
|
817
|
+
- With `editAs`, the same fields are locked in the other language, and a
|
|
818
|
+
save that would change one is refused (shown as an error, not sent).
|
|
819
|
+
- In a custom language without `spans`, a field is checked by value: no
|
|
820
|
+
edit is refused. While the text does not parse, or reads another
|
|
821
|
+
read-only value, edits go through and `save()` waits (returns `false`,
|
|
822
|
+
saying which field) until the text holds every locked value again.
|
|
823
|
+
|
|
824
|
+
</details>
|
|
825
|
+
|
|
826
|
+
### Secrets
|
|
827
|
+
|
|
828
|
+
Fields the schema marks `writeOnly: true` or `x-secret: true` are secrets.
|
|
829
|
+
The host sends a placeholder instead of the value, and the editor keeps it
|
|
830
|
+
unless the user replaces it:
|
|
831
|
+
|
|
832
|
+
```ts
|
|
833
|
+
const editor = new ConfigEditor(element, {
|
|
834
|
+
language: "yaml",
|
|
835
|
+
value: "tls:\n key: «secret 3f2a»\n",
|
|
836
|
+
schema,
|
|
837
|
+
secrets: {
|
|
838
|
+
placeholder: "«secret [0-9a-f]+»", // the default (Rust regex syntax)
|
|
839
|
+
isPlaceholder: (token) => knownTokens.has(token), // optional
|
|
840
|
+
hint: "Keeps the current secret unless you replace it",
|
|
841
|
+
referencePrefixes: ["${", "file:"],
|
|
842
|
+
},
|
|
843
|
+
});
|
|
844
|
+
```
|
|
845
|
+
|
|
846
|
+
<details>
|
|
847
|
+
<summary>How placeholders behave: where they count, what throws, atomic editing, chips, references, validation</summary>
|
|
848
|
+
|
|
849
|
+
- A placeholder is real only in the field of the host's own `value` it
|
|
850
|
+
was given in (and accepted by `isPlaceholder`). Anywhere else it is plain
|
|
851
|
+
text, so it never stands for another field's secret: one of the host's
|
|
852
|
+
tokens pasted into another field, or its field's own key renamed, is
|
|
853
|
+
flagged, and so is a token the host did not give in a secret field. Put
|
|
854
|
+
back into its own field it is real again. It follows its field when the
|
|
855
|
+
path to it changes but not the field: a list item deleted, inserted or
|
|
856
|
+
moved before it, or a key above it renamed (`db` made `database`). A token the host wrote in a comment is real
|
|
857
|
+
in that text's comments only: pasted into a field it is flagged, as a
|
|
858
|
+
field's token is in a comment, each where it is written.
|
|
859
|
+
- A token is opaque: whatever `placeholder` matches, kept whole as written;
|
|
860
|
+
nothing is read from inside it, so the same token in two fields stands
|
|
861
|
+
for each field's own secret. Make the pattern match your tokens exactly
|
|
862
|
+
(`«secret [0-9a-f]{8}»`, not `«.*»`): text it does not match (`«hidden»`)
|
|
863
|
+
is plain text. `placeholder` must be a regular expression
|
|
864
|
+
that matches no empty text (`.*` throws). An exception `isPlaceholder`
|
|
865
|
+
throws is logged, and the token is not real. `referencePrefixes` must be
|
|
866
|
+
non-empty strings.
|
|
867
|
+
- A placeholder is atomic: the caret never lands inside, `Backspace` and
|
|
868
|
+
`Delete` remove it whole, an edit cutting into it replaces it whole (a
|
|
869
|
+
placeholder pasted over another, or by a bare `insertFromPaste` input,
|
|
870
|
+
stays whole), and
|
|
871
|
+
copying keeps its text. It shows as a chip (color tokens `secret-chip`,
|
|
872
|
+
`secret-chip-border`) with a key in the gutter; hovering shows `hint`.
|
|
873
|
+
- In a secret field, suggestions offer `${VAR}` and `file:` references, also
|
|
874
|
+
on a placeholder (accepting one replaces it).
|
|
875
|
+
- The schema check accepts an untouched placeholder (no `pattern`,
|
|
876
|
+
`format`, length or type problem), also one alone in a string written
|
|
877
|
+
over lines (a YAML block scalar, a TOML `"""` string, an HCL heredoc, XML
|
|
878
|
+
text on its own line), and `editAs` and saving keep it
|
|
879
|
+
byte-for-byte. Nothing the editor shows, says or hands back (problems,
|
|
880
|
+
hover, announcements, the diff preview, copies, `onChange`, console
|
|
881
|
+
messages) holds a token the host did not send.
|
|
882
|
+
- That holds for what the host sends: the editor shows the host's texts as
|
|
883
|
+
given. The `baseline` is shown too (the diff gutter, the change preview,
|
|
884
|
+
`unifiedDiff`), so it must hold the same placeholders as `value`, never
|
|
885
|
+
the stored secrets. A real value sent in a secret field (`value`,
|
|
886
|
+
`baseline`, a document of a `ConfigDocuments`, whose hidden documents stay
|
|
887
|
+
mounted) is shown, copied and handed back like any other text: send the
|
|
888
|
+
file with its secrets replaced by placeholders, never as it was loaded.
|
|
889
|
+
- Editing in `language`, `onChange` hands back exactly the text on screen
|
|
890
|
+
with the host's line endings, byte order mark, final newline, tabs and
|
|
891
|
+
quoting (placeholders included); a text that did not change is not
|
|
892
|
+
reported. In `editAs`, the value handed back is the conversion back to
|
|
893
|
+
`language`: a host that writes the text out as is must write that value.
|
|
894
|
+
|
|
895
|
+
</details>
|
|
896
|
+
|
|
897
|
+
### Paths
|
|
898
|
+
|
|
899
|
+
A path names a field the same way in every language: a JSON pointer
|
|
900
|
+
(`"/web/hosts/1"`, `""` for the whole document; as RFC 6901 has it, `"/"`
|
|
901
|
+
is the key `""`) or its keys and indices (`["web", "hosts", 1]`). A pointer starts with `/`: `"web/hosts"` throws,
|
|
902
|
+
everywhere a path is taken (the editor's methods, the tools,
|
|
903
|
+
`readOnlyPaths`, host diagnostics). Each segment is verbatim (`"/ a"` is
|
|
904
|
+
the key `" a"`; `~1` is `/` and `~0` is `~`), and only `0` or digits
|
|
905
|
+
without a leading zero index a list, where the value is one (in an object
|
|
906
|
+
`"/1"` is the key `"1"`; `"/01"` is always a key). A path the document does
|
|
907
|
+
not have (a missing parent, list index or leaf) is found nowhere: `rangeOf`
|
|
908
|
+
gives `null`, `reveal` `false`, a lock there locks nothing, and a host
|
|
909
|
+
problem there is shown for the whole document, naming its path. An index names an item only where there is a list: a list written as
|
|
910
|
+
one, repeated XML elements or HCL blocks, and the element or block
|
|
911
|
+
written once, which XML and HCL read as a one-item list too (`/web/0` is
|
|
912
|
+
`<web>` or `web { }` written once). An index on anything else is found
|
|
913
|
+
nowhere: on a scalar, an object, an attribute, HCL blocks keyed by their
|
|
914
|
+
labels (`/service/0` beside `service "api" { }`), another index
|
|
915
|
+
(`/web/0/0`) or the document (`/0`).
|
|
916
|
+
|
|
917
|
+
```ts
|
|
918
|
+
editor.reveal("/web/listen"); // scroll to it, select it, focus; false when absent
|
|
919
|
+
editor.revealRange({ start: 0, end: 12 }); // any stretch of the text on screen, a comment included
|
|
920
|
+
editor.rangeOf(["web", "listen"]);
|
|
921
|
+
// { start: 31, end: 43, startLine: 3, startColumn: 3, endLine: 3, endColumn: 15 } or null
|
|
922
|
+
editor.pathAt(35); // { pointer: "/web/listen", segments: ["web", "listen"] } or null
|
|
923
|
+
editor.currentPath; // the caret's path
|
|
924
|
+
new ConfigEditor(element, {
|
|
925
|
+
onPathChange: (path) => (crumb.textContent = path.pointer || "/"),
|
|
926
|
+
});
|
|
927
|
+
```
|
|
928
|
+
|
|
929
|
+
`start`/`end` and `pathAt`'s index are string indices (UTF-16 units) into the
|
|
930
|
+
text on screen, `text` (the `editAs` language while editing as another one),
|
|
931
|
+
the lines of closed folds included; lines and columns are one-based. The
|
|
932
|
+
text area leaves a closed fold's lines out, so its `selectionStart` names the
|
|
933
|
+
same place only while no fold is closed: follow the caret with
|
|
934
|
+
`currentPath` / `onPathChange`. `reveal` and `rangeOf` cover the key
|
|
935
|
+
and its value when they share a line (`listen: 7835`, `<listen>7835</listen>`),
|
|
936
|
+
the key alone when the value is a block below it, the value alone for a list
|
|
937
|
+
item, and the dash or header of an item holding a block (`- name: web`, a
|
|
938
|
+
repeated HCL block, a TOML `[[array]]` entry). `pathAt` gives the key under or just before the index, else the
|
|
939
|
+
value or container holding it (`""` at the top level).
|
|
940
|
+
`revealRange({ start, end })` does what `reveal` does for any stretch of the
|
|
941
|
+
text on screen (string indices, as `rangeOf` gives them, so
|
|
942
|
+
`editor.revealRange(editor.rangeOf(path))` is `reveal(path)`): it selects
|
|
943
|
+
it, scrolls it into view inside the editor and focuses the editor, leaving
|
|
944
|
+
the page where it is. A range past the end is clamped to it; `false` before
|
|
945
|
+
the editor mounts and for an empty document.
|
|
946
|
+
|
|
947
|
+
## Languages and themes
|
|
948
|
+
|
|
949
|
+
The main entry also lists what the editor accepts, for pickers and file
|
|
950
|
+
handling (after `loadConfigEditor()`):
|
|
951
|
+
|
|
952
|
+
| Function | Returns | Description |
|
|
953
|
+
| ------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
954
|
+
| `languages()` | `LanguageInfo[]` | The built-in and registered languages: `{ name, label, icon, extensions, defaultFileName }` each (`name` is what `language` and `editAs` take). |
|
|
955
|
+
| `themes()` | `ThemeInfo[]` | The bundled themes: `{ name, label, dark }` each (`name` is what `theme` takes, `label` its display name, `dark` whether it is a dark theme). |
|
|
956
|
+
| `languageForFile(path)` | `string \| null` | The language of a file from its extension (`"main.tf"` gives `"hcl"`), registered languages included. |
|
|
957
|
+
| `registerLanguage(definition)` | `string` | Add a custom language (written in JavaScript); returns its name. See [Custom languages](#custom-languages). |
|
|
958
|
+
|
|
959
|
+
```js
|
|
960
|
+
import { languageForFile, languages, themes } from "@pngwasi/config-editor";
|
|
961
|
+
|
|
962
|
+
languageForFile("deploy/main.tf"); // "hcl"
|
|
963
|
+
languages().find((language) => language.extensions.includes("yml"));
|
|
964
|
+
// { name: "yaml", label: "YAML", icon: "Y", extensions: ["yaml", "yml"], defaultFileName: "untitled.yaml" }
|
|
965
|
+
for (const theme of themes())
|
|
966
|
+
picker.append(new Option(theme.label, theme.name));
|
|
967
|
+
```
|
|
968
|
+
|
|
969
|
+
### XML mapping
|
|
970
|
+
|
|
971
|
+
Child elements and attributes are object properties, element text is a typed
|
|
972
|
+
scalar (`<listen>7835</listen>` is the number 7835; where the schema wants a
|
|
973
|
+
number, text in any number spelling is one: `1.50`, `1e3`, `4`, kept as
|
|
974
|
+
written; empty text is `null` where the schema allows it and no string), and repeated siblings are
|
|
975
|
+
an array. An attribute sharing its name with a child element is the property
|
|
976
|
+
`@name` (`<r a="1"><a>2</a></r>` is `{"r": {"@a": 1, "a": 2}}`), so the two
|
|
977
|
+
stay apart. Another host's `@name` key holding a value (an npm `@scope`) is
|
|
978
|
+
shown as the attribute `name` in an XML view and saved back as `@name`
|
|
979
|
+
(converted alone, it is a loss: it reads back `name`); one holding a map or
|
|
980
|
+
list, and a `#text` beside child keys, make the switch to XML wait. A top-level element marked `config-root="true"` is a transparent
|
|
981
|
+
wrapper; without it, every top-level element is a document property, so a
|
|
982
|
+
file may hold one top-level element or several (a fragment). The editor never
|
|
983
|
+
adds a root: `{"listen": 4343, "port": 80}` writes `<listen>4343</listen>` and
|
|
984
|
+
`<port>80</port>`, and a key added at the top in another view is one more
|
|
985
|
+
top-level element.
|
|
986
|
+
|
|
987
|
+
Namespace declarations (`xmlns`, `xmlns:m`) and the attributes of the XML
|
|
988
|
+
Schema instance namespace (`xsi:schemaLocation`, `xsi:type`, with whatever
|
|
989
|
+
prefix is bound to it) are markup, not data: `<project xmlns="…"
|
|
990
|
+
xmlns:xsi="…" xsi:schemaLocation="…">` reads as `{"project": {…}}` with its
|
|
991
|
+
elements only, so a schema need not list them (a closed `pom.xml` schema
|
|
992
|
+
finds nothing wrong), and completion, hover and other views do not show them.
|
|
993
|
+
They stay editable as text in the XML view, and every save from another view
|
|
994
|
+
keeps them byte for byte where the file has them. A key spelled as one
|
|
995
|
+
(`xmlns:y`) is not written to XML: the save or conversion waits, saying to
|
|
996
|
+
write it in the XML text. Converting a file to another language leaves them
|
|
997
|
+
behind, as it does comments. Other prefixed attributes (`m:kind`) are data,
|
|
998
|
+
keyed by the name as written.
|
|
999
|
+
|
|
1000
|
+
## `@pngwasi/config-editor/tools`
|
|
1001
|
+
|
|
1002
|
+
The editor's answers about a text, without an editor: for a server, a
|
|
1003
|
+
build step or a review screen. They need the WebAssembly module loaded:
|
|
1004
|
+
`loadConfigEditor()`, which this entry exports too. A `schema` argument is a
|
|
1005
|
+
JSON Schema as JSON or YAML text, as the editor's `schema` option takes.
|
|
1006
|
+
|
|
1007
|
+
| Function | Returns | Description |
|
|
1008
|
+
| ------------------------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1009
|
+
| `validate(language, text, schema?)` | `Diagnostic[]` | Syntax problems, plus schema problems when a schema is given. The schema is compiled once and kept for the next call with the same text (`convert` and `schemaWarnings` share it). |
|
|
1010
|
+
| `convert(from, text, to, schema?)` | `{ text, losses }` | Convert between languages. `losses` lists JSON pointers of values the target reads back differently (an infinity or `NaN` is written as the text `inf` or `nan` in JSON, HCL and XML, and listed). Throws when the text does not parse or the target cannot express it at all (TOML has no `null`). With a schema, a lone XML element where it expects a list converts as a one-item list. |
|
|
1011
|
+
| `unifiedDiff(baseline, current, context?)` | `string` | The `diff -u` of two texts: `--- baseline` / `+++ current` headers, then `@@` hunks with `context` lines around each change (default 3). `""` when they have the same lines; line endings are compared as LF. |
|
|
1012
|
+
| `changeSummary(baseline, current)` | `ChangeSummary` | `{ added, removed, modified, hunks }` between two texts, as the diff gutter and `onChangeSummary` count them: a final line break added is the empty last line added, one removed is no change (no line goes), where `unifiedDiff` writes both as `diff -u` does (the last line changed, ``). |
|
|
1013
|
+
| `parse(language, text)` | `unknown` | The document as plain data (objects, arrays, strings, numbers, booleans, `null`): the model schema validation sees, the same in every language. YAML's `.inf`/`.nan` and TOML's `inf`/`nan` are `Infinity`, `-Infinity` and `NaN`. An integer past 2^53 (TOML and YAML hold 64-bit ones) is a `bigint`, exact, and `serialize` takes one back; one past 64 bits, or a JSON number past a float's range (`1e400`), is a syntax error, in the editor too. A YAML number with a leading zero (`012`) is the string it is written as (YAML 1.1 read it as octal, 1.2 as decimal). |
|
|
1014
|
+
| `serialize(language, value)` | `string` | Plain data as a document, only when it reads back as exactly that value (the check `convert`'s `losses` make). Throws when the value is not plain data (a `Date`, `Map`, `Set` or class instance throws: pass a date's `toISOString()`) or the language cannot express it exactly (TOML has no `null`; XML has no empty, nested or one-item list). In every language, as `JSON.stringify` does, an object member set to `undefined` is left out, and an `undefined` or a hole in an array throws. |
|
|
1015
|
+
| `rangeOf(language, text, path)` | `EditorRange \| null` | Where a field is written in a text, as the editor's `rangeOf` answers; see [Paths](#paths). |
|
|
1016
|
+
| `rangesOf(language, text, paths)` | `(EditorRange \| null)[]` | `rangeOf` for each of many paths, in order, the text read once for all of them (thousands of paths one by one each read it again). |
|
|
1017
|
+
| `pathAt(language, text, index)` | `EditorPath \| null` | The path at a string index of a text, as the editor's `pathAt` answers. |
|
|
1018
|
+
| `schemaWarnings(schema)` | `string[]` | What the editor cannot use in a schema (the messages `onSchemaWarning` receives). Throws on an invalid schema. |
|
|
1019
|
+
| `presetCss()` | `string` | The stylesheet the editor injects (layout and every theme), for `styled: false`. |
|
|
1020
|
+
|
|
1021
|
+
```ts
|
|
1022
|
+
interface Diagnostic {
|
|
1023
|
+
line?: number; // one-based; absent when the problem has no position
|
|
1024
|
+
column?: number;
|
|
1025
|
+
endColumn?: number; // just past the marker, on endLine when it is set
|
|
1026
|
+
endLine?: number; // only when the marker covers several lines
|
|
1027
|
+
message: string;
|
|
1028
|
+
severity: "error" | "warning" | "info" | "hint";
|
|
1029
|
+
origin: "editor" | "host"; // who found it (`validate` and `onProblems`: always "editor")
|
|
1030
|
+
deprecated?: boolean; // true on a deprecated key's warning (the marker is the key)
|
|
1031
|
+
}
|
|
1032
|
+
```
|
|
1033
|
+
|
|
1034
|
+
```js
|
|
1035
|
+
import {
|
|
1036
|
+
convert,
|
|
1037
|
+
loadConfigEditor,
|
|
1038
|
+
parse,
|
|
1039
|
+
rangeOf,
|
|
1040
|
+
rangesOf,
|
|
1041
|
+
serialize,
|
|
1042
|
+
validate,
|
|
1043
|
+
} from "@pngwasi/config-editor/tools";
|
|
1044
|
+
|
|
1045
|
+
await loadConfigEditor();
|
|
1046
|
+
|
|
1047
|
+
validate("json", '{"insecure_plaintext": "yes"}', schemaText);
|
|
1048
|
+
// [{ line: 1, column: 24, endColumn: 29, severity: "error", origin: "editor",
|
|
1049
|
+
// message: '/insecure_plaintext: "yes" is not of type "boolean"' }]
|
|
1050
|
+
|
|
1051
|
+
// At most 20 problems are listed; past that, a 21st without a position says
|
|
1052
|
+
// more follow (the footer shows it too).
|
|
1053
|
+
|
|
1054
|
+
convert("yaml", "listen: 7835\n", "toml");
|
|
1055
|
+
// { text: "listen = 7835\n", losses: [] }
|
|
1056
|
+
|
|
1057
|
+
parse("toml", "[web]\nhttp = 80\n"); // { web: { http: 80 } }
|
|
1058
|
+
serialize("hcl", { web: { http: 80 } }); // "web {\n http = 80\n}\n"
|
|
1059
|
+
rangeOf("yaml", "web:\n http: 80\n", "/web/http");
|
|
1060
|
+
// { start: 7, end: 15, startLine: 2, startColumn: 3, endLine: 2, endColumn: 11 }
|
|
1061
|
+
rangesOf("yaml", "web:\n http: 80\n", ["/web/http", "/web/https"]);
|
|
1062
|
+
// [{ start: 7, end: 15, … }, null]
|
|
1063
|
+
```
|
|
1064
|
+
|
|
1065
|
+
## `@pngwasi/config-editor/binding`
|
|
1066
|
+
|
|
1067
|
+
React, Vue and Svelte have packages of their own, built on what this
|
|
1068
|
+
entry exports (`EditorBinding`, `DocumentsBinding`, `SETTING_TYPES`):
|
|
1069
|
+
|
|
1070
|
+
| Package | Component |
|
|
1071
|
+
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
|
|
1072
|
+
| [`@pngwasi/config-editor-react`](https://github.com/paradoxe35/config-editor/tree/main/js/config-editor-react) | `<ConfigEditor value onChange />`, a ref for the instance API |
|
|
1073
|
+
| [`@pngwasi/config-editor-vue`](https://github.com/paradoxe35/config-editor/tree/main/js/config-editor-vue) | `<ConfigEditor v-model @save />`, a template ref |
|
|
1074
|
+
| [`@pngwasi/config-editor-svelte`](https://github.com/paradoxe35/config-editor/tree/main/js/config-editor-svelte) | `<ConfigEditor bind:value onSave />`, exported functions |
|
|
1075
|
+
|
|
1076
|
+
For another framework (Angular, Solid, Lit, …), `EditorBinding` is what
|
|
1077
|
+
those components do, written once: feed it the component's props and it
|
|
1078
|
+
decides what each change means. Settings and most props apply live (the
|
|
1079
|
+
caret, undo history and folds stay); `language`, `schema`, `fileName`,
|
|
1080
|
+
`editorClassName` and the `secrets` patterns re-mount the editor, carrying
|
|
1081
|
+
the document, its baseline, the caret and the echoes still on their way
|
|
1082
|
+
over; the bound value is kept in step so a late echo never rolls the
|
|
1083
|
+
document back (an edit the framework passes back in late is told apart
|
|
1084
|
+
from a value the app sets, such as a reset or a loaded file); a mount
|
|
1085
|
+
that failed on a bad prop is retried when a prop changes; the WebAssembly
|
|
1086
|
+
loads once (`loadConfigEditor`); and `handle` is the instance API
|
|
1087
|
+
(`ConfigEditorHandle`: `value`, `setValue`, `reveal`, `save`, `isDirty`, …).
|
|
1088
|
+
Each prop that changes reaches the editor through `update`: a setting no
|
|
1089
|
+
longer passed returns to its default.
|
|
1090
|
+
|
|
1091
|
+
```ts
|
|
1092
|
+
import { EditorBinding } from "@pngwasi/config-editor/binding";
|
|
1093
|
+
|
|
1094
|
+
const binding = new EditorBinding("my-framework-config-editor");
|
|
1095
|
+
// When the component's element exists (props named as React's:
|
|
1096
|
+
// `value`, `onChange`, `editorClassName`, every setting, …):
|
|
1097
|
+
binding.attach(element, {
|
|
1098
|
+
value,
|
|
1099
|
+
onChange: (text) => emit(text),
|
|
1100
|
+
language: "yaml",
|
|
1101
|
+
});
|
|
1102
|
+
// After every change of the props (unchanged ones cost nothing):
|
|
1103
|
+
binding.update({
|
|
1104
|
+
value,
|
|
1105
|
+
onChange: (text) => emit(text),
|
|
1106
|
+
language: "yaml",
|
|
1107
|
+
theme,
|
|
1108
|
+
});
|
|
1109
|
+
// The instance API, for the component's users:
|
|
1110
|
+
binding.handle.reveal("/web/listen");
|
|
1111
|
+
// On unmount: the editor is destroyed and freed.
|
|
1112
|
+
binding.detach();
|
|
1113
|
+
```
|
|
1114
|
+
|
|
1115
|
+
<details>
|
|
1116
|
+
<summary>DocumentsBinding, unmounting from a callback, SETTING_TYPES, and binding from a vanilla app</summary>
|
|
1117
|
+
|
|
1118
|
+
`DocumentsBinding` does the same for a `ConfigDocuments` view (`label`,
|
|
1119
|
+
`viewClassName` and whether `onClose` is set re-mount; a new `activeId`
|
|
1120
|
+
shows that document). A component unmounted from inside a callback (state
|
|
1121
|
+
set in `onChange` that hides it) is destroyed when the framework commits
|
|
1122
|
+
that, after the callback returns: React and Svelte do so asynchronously,
|
|
1123
|
+
so the callbacks the same edit fires next (`onChangeSummary`,
|
|
1124
|
+
`onDirtyChange`) still arrive first; after `detach()` none does. `SETTING_TYPES` is every setting's key and the
|
|
1125
|
+
JavaScript type of its values, generated from the Rust struct: plain data,
|
|
1126
|
+
readable before the WebAssembly loads (Vue declares its props from it, and
|
|
1127
|
+
`Object.keys(SETTING_TYPES)` picks the settings out of a component's props).
|
|
1128
|
+
|
|
1129
|
+
A vanilla app can use `EditorBinding` too: it is plain JavaScript. It
|
|
1130
|
+
pays off when the app re-renders from state and passes every prop each
|
|
1131
|
+
time (a web component, Lit, a store of your own); an app that creates an
|
|
1132
|
+
editor and changes an option now and then is simpler with `new
|
|
1133
|
+
ConfigEditor` and `update()`.
|
|
1134
|
+
|
|
1135
|
+
</details>
|
|
1136
|
+
|
|
1137
|
+
## Keyboard
|
|
1138
|
+
|
|
1139
|
+
**Writing**
|
|
1140
|
+
|
|
1141
|
+
- `Ctrl+Space`: suggestions; `↑` / `↓` and `PageUp` / `PageDown` move in
|
|
1142
|
+
the list, `Enter` or `Tab` accepts one; `Tab` after accepting a block
|
|
1143
|
+
goes to the next empty value it wrote, or selects the next value
|
|
1144
|
+
- `Tab` / `Shift+Tab`: indent / outdent
|
|
1145
|
+
- `Ctrl+/`: comment or uncomment the lines
|
|
1146
|
+
- `Ctrl+Enter` / `Ctrl+Shift+Enter`: new line below / above
|
|
1147
|
+
- `Alt+↑` / `Alt+↓`: move the line or selected lines up / down (a folded
|
|
1148
|
+
line with its hidden lines, staying folded; past a folded block, over all
|
|
1149
|
+
of it)
|
|
1150
|
+
- `Shift+Alt+↑` / `Shift+Alt+↓`: copy the line or selected lines up / down
|
|
1151
|
+
- `Ctrl+Shift+K`: delete the line or selected lines (the caret keeps its column)
|
|
1152
|
+
- `Ctrl+]` / `Ctrl+[`: indent / outdent the line or selected lines
|
|
1153
|
+
- `Ctrl+C` / `Ctrl+X` with nothing selected: copy / cut the whole line
|
|
1154
|
+
(pasting it inserts above)
|
|
1155
|
+
- `Ctrl+Z`, `Ctrl+Shift+Z` / `Ctrl+Y`: undo, redo (the last 500 steps, fewer in a large text: they keep up to 64 MB of earlier texts)
|
|
1156
|
+
- `Ctrl+S`: save (with `onSave`)
|
|
1157
|
+
- `Escape`: close what is open (suggestions, a preview, a widget)
|
|
1158
|
+
|
|
1159
|
+
**Finding your way**
|
|
1160
|
+
|
|
1161
|
+
- `Ctrl+F` / `Ctrl+H`: find / find and replace; `Enter` and `Shift+Enter` (or `F3` / `Shift+F3`) next / previous match; in the replace field `Enter` replaces the match and `Ctrl+Alt+Enter` all of them (one undo step)
|
|
1162
|
+
- `Alt+C` / `Alt+W` / `Alt+R` in find: match case / whole word / regular expression
|
|
1163
|
+
- `Ctrl+G`: go to a line (`line` or `line:column`)
|
|
1164
|
+
- `F8` / `Shift+F8`: next / previous problem
|
|
1165
|
+
- `Alt+Enter`: open the documentation of the problem at the caret (a problem with a docs link), else the hover card's Documentation link
|
|
1166
|
+
- `F6`: while the "file changed outside the editor" notice is open, move to its choices and back
|
|
1167
|
+
- `Ctrl+K Ctrl+I`: show the schema docs of the key at the caret (read to
|
|
1168
|
+
screen readers, its Documentation link too; `Escape` closes them; in
|
|
1169
|
+
`Ctrl+M` mode `Tab` moves into its links); on a touch screen, a tap on a
|
|
1170
|
+
key shows them
|
|
1171
|
+
- `Ctrl+K Ctrl+I` again: focus those docs (or the problems' tip shown at
|
|
1172
|
+
the caret): the arrows, `PageUp` / `PageDown`, `Home` and `End` scroll
|
|
1173
|
+
them, `Tab` reaches their links, `Enter` or `Alt+Enter` opens their docs
|
|
1174
|
+
link, `Escape` returns to the text
|
|
1175
|
+
- `PageDown` / `PageUp` (with `Shift`, selecting): move the caret a page in
|
|
1176
|
+
the text; the host page never scrolls
|
|
1177
|
+
|
|
1178
|
+
**Changes against the baseline**
|
|
1179
|
+
|
|
1180
|
+
- `Alt+F5` / `Shift+Alt+F5`: next / previous change (announced, as `F8` is)
|
|
1181
|
+
- `Alt+F3` / `Shift+Alt+F3`: the same, opening its preview, where `Enter` or `R` reverts the change
|
|
1182
|
+
|
|
1183
|
+
**Folding**
|
|
1184
|
+
|
|
1185
|
+
- `Ctrl+Shift+[` / `Ctrl+Shift+]`: fold / unfold at the caret
|
|
1186
|
+
- `Ctrl+K Ctrl+0` / `Ctrl+K Ctrl+J`: fold / unfold everything
|
|
1187
|
+
|
|
1188
|
+
**Documents** (a `ConfigDocuments` view)
|
|
1189
|
+
|
|
1190
|
+
- `Alt+PageDown` / `Alt+PageUp`: next / previous document
|
|
1191
|
+
|
|
1192
|
+
**Leaving the editor**
|
|
1193
|
+
|
|
1194
|
+
- `Ctrl+M`: toggle "Tab moves focus"
|
|
1195
|
+
- `Escape`, then `Tab` / `Shift+Tab`: leave the editor once
|
|
1196
|
+
|
|
1197
|
+
`Cmd` works in place of `Ctrl` on macOS, but for `Ctrl+Y` (redo is
|
|
1198
|
+
`Cmd+Shift+Z` there), `Ctrl+Space` and `Ctrl+M`, which macOS keeps for
|
|
1199
|
+
itself. The shortcuts the editor names (button tooltips) say `Cmd` on macOS and
|
|
1200
|
+
iOS where `Cmd` works, and `Ctrl` elsewhere: a text of the `strings` setting
|
|
1201
|
+
writes `{cmd}` for that key, and one without it is shown as written. On a touch
|
|
1202
|
+
screen the footer says suggestions appear as you type, not a key
|
|
1203
|
+
(`suggestionsHintTouch`).
|
|
1204
|
+
|
|
1205
|
+
### Leaving the editor and screen readers
|
|
1206
|
+
|
|
1207
|
+
`Tab` indents while editing. `Ctrl+M` switches `Tab` and `Shift+Tab` to
|
|
1208
|
+
moving the focus out of the editor (announced, and shown in the footer as
|
|
1209
|
+
"Tab moves focus" until `Ctrl+M` again or a click on it); right after an
|
|
1210
|
+
`Escape` that had nothing to close, one `Tab` or `Shift+Tab` leaves. `Tab`
|
|
1211
|
+
still accepts an open suggestion. The text area's `aria-describedby` holds
|
|
1212
|
+
what is at the caret: each problem's message (host ones with their source),
|
|
1213
|
+
a read-only value's reason, a secret placeholder's hint; `F8` announces
|
|
1214
|
+
"Error 2 of 5: …". A save the editor refuses (the text does not parse) is
|
|
1215
|
+
announced with its reason; a save it sends is not: your `onSave` owns the
|
|
1216
|
+
result (the write can still fail on your side), so announce "Saved" from
|
|
1217
|
+
your page once it is done. On a touch screen a tap on underlined or read-only text
|
|
1218
|
+
shows its message, and selections made with a long press or the handles are
|
|
1219
|
+
followed. Nothing to configure:
|
|
1220
|
+
|
|
1221
|
+
```ts
|
|
1222
|
+
const editor = new ConfigEditor(element, { value, language: "yaml" });
|
|
1223
|
+
// Tab out with Ctrl+M or Escape, Tab; screen readers hear the caret's problem.
|
|
1224
|
+
```
|
|
1225
|
+
|
|
1226
|
+
### Folding
|
|
1227
|
+
|
|
1228
|
+
Lines that start a block (a YAML mapping, a JSON object, a TOML table, an
|
|
1229
|
+
HCL block, an XML element, a run of comments, a multi-line string) get a
|
|
1230
|
+
chevron in the gutter, shown while the pointer is over it and always on a
|
|
1231
|
+
folded line, as in VS Code. A folded line shows `…`; clicking it or the
|
|
1232
|
+
chevron opens it.
|
|
1233
|
+
|
|
1234
|
+
```ts
|
|
1235
|
+
editor.foldAll();
|
|
1236
|
+
editor.unfold("/web/listen"); // show one field; false when nothing was folded around it
|
|
1237
|
+
editor.fold(["clients"]); // fold the block its key opens; false when there is none
|
|
1238
|
+
```
|
|
1239
|
+
|
|
1240
|
+
<details>
|
|
1241
|
+
<summary>How folds behave through edits and caret moves</summary>
|
|
1242
|
+
|
|
1243
|
+
Folding only changes the view: `value`, `onChange`, undo and saving see the
|
|
1244
|
+
whole text, and copying a selection across a fold copies the hidden lines.
|
|
1245
|
+
An edit that touches a fold (typing at the end of a folded line, Backspace
|
|
1246
|
+
at the start of the next one, a paste over a selection reaching into it)
|
|
1247
|
+
opens it first, and whatever moves the caret into a fold (find, go to line,
|
|
1248
|
+
`F8`, `reveal`, a click on a problem) opens it. A folded block hiding an
|
|
1249
|
+
error or changes marks its line. The text area holds the text on screen
|
|
1250
|
+
without the lines of closed folds, so read the document from `value` (or
|
|
1251
|
+
`text`), not from the element.
|
|
1252
|
+
|
|
1253
|
+
</details>
|
|
1254
|
+
|
|
1255
|
+
### Sticky scroll
|
|
1256
|
+
|
|
1257
|
+
While the text scrolls, the lines that open the blocks around the top line
|
|
1258
|
+
(parent keys, tables, elements) stay at the top, outermost first, as in VS
|
|
1259
|
+
Code; the innermost is pushed up as its block ends, and a click on one
|
|
1260
|
+
scrolls back to it with the caret at its start. A root that only opens a
|
|
1261
|
+
bracket (JSON's `{`) does not stick. They come from the same
|
|
1262
|
+
blocks as folding (also with `folding: false`), in every language and in an
|
|
1263
|
+
Edit-as view, and show the text as the editor does (colors, locked values,
|
|
1264
|
+
secret placeholders). Screen readers skip them (they read the text itself),
|
|
1265
|
+
and a caret moved under them scrolls back into view below them.
|
|
1266
|
+
|
|
1267
|
+
```ts
|
|
1268
|
+
const editor = new ConfigEditor(element, { value, stickyScrollMaxLines: 3 });
|
|
1269
|
+
editor.update({ stickyScroll: false }); // off
|
|
1270
|
+
```
|
|
1271
|
+
|
|
1272
|
+
## Saving and unsaved edits
|
|
1273
|
+
|
|
1274
|
+
Nothing is saved by itself: `Ctrl+S` / `Cmd+S` in the editor (and
|
|
1275
|
+
`editor.save()`) calls `onSave` with the document in `language`. Text that
|
|
1276
|
+
does not parse, its line breaks read as the editor reads them (LF, CRLF and
|
|
1277
|
+
a lone CR each end a line), is never saved, in any language: nothing is
|
|
1278
|
+
sent, `save()` returns `false`, and the caret goes to the syntax error
|
|
1279
|
+
(`onChange` still hears every edit). The host's own line breaks are kept as
|
|
1280
|
+
it wrote them: a lone CR in a TOML or HCL text, shown as its reader's syntax
|
|
1281
|
+
error, does not hold a save back (see Line endings below). Text written beside a secret placeholder the host gave as
|
|
1282
|
+
a field's whole value waits the same way, its message shown. While editing as another language, an edit still waiting
|
|
1283
|
+
out the typing pause is converted first; when it cannot be written in
|
|
1284
|
+
`language` (invalid, or a `null` for TOML), the save waits the same way.
|
|
1285
|
+
The document is dirty while it differs from `baseline` (the document at
|
|
1286
|
+
mount when no `baseline` is given). Embedding notes (what is fixed at mount,
|
|
1287
|
+
which text to send, flushing before your own Save button) are in the crate's
|
|
1288
|
+
[Embedding](https://github.com/paradoxe35/config-editor/tree/main/crates/config-editor-leptos#embedding)
|
|
1289
|
+
section: `editor.value` is the document in `language`, `editor.text` the
|
|
1290
|
+
text on screen.
|
|
1291
|
+
|
|
1292
|
+
<details>
|
|
1293
|
+
<summary>Line endings (CRLF, LF and CR, mixed in one text)</summary>
|
|
1294
|
+
|
|
1295
|
+
Line endings are kept: when the host's text ends its lines with CRLF,
|
|
1296
|
+
`onChange` and `onSave` receive CRLF too (the editor works on LF text inside,
|
|
1297
|
+
and dirty state and the diff compare line endings as LF). Each line keeps its
|
|
1298
|
+
own: in a text mixing CRLF, LF and old Mac CR endings, an untouched line ends
|
|
1299
|
+
as it did, an edited line keeps its ending, and a new line takes the ending
|
|
1300
|
+
of the line above (the text's most common one when there is none). A lone CR
|
|
1301
|
+
that the language does not read as a line break (TOML, HCL) is shown as the
|
|
1302
|
+
syntax error its reader gives (as `parse` reports it), until that line is
|
|
1303
|
+
edited (an edited line then takes a break the language reads); it does not hold a save back, and the save keeps it as it was. Every position the tools give or take (`validate`, `rangeOf`,
|
|
1304
|
+
`pathAt`, `parse` errors) counts LF, CRLF and a lone CR each as one line
|
|
1305
|
+
break, as the editor does.
|
|
1306
|
+
|
|
1307
|
+
</details>
|
|
1308
|
+
|
|
1309
|
+
```js
|
|
1310
|
+
const editor = new ConfigEditor(element, {
|
|
1311
|
+
value: loaded,
|
|
1312
|
+
baseline: loaded,
|
|
1313
|
+
onSave: async (text) => {
|
|
1314
|
+
await putConfig(text);
|
|
1315
|
+
editor.update({ baseline: text }); // saved: nothing is unsaved any more
|
|
1316
|
+
},
|
|
1317
|
+
onDirtyChange: (dirty) => (saveButton.disabled = !dirty),
|
|
1318
|
+
onBaselineConflict: (event) => console.log("baseline conflict:", event),
|
|
1319
|
+
});
|
|
1320
|
+
// Saved outside the editor: the baseline moves on.
|
|
1321
|
+
events.on("config-changed", (text) => editor.update({ baseline: text }));
|
|
1322
|
+
```
|
|
1323
|
+
|
|
1324
|
+
A new baseline while the user has unsaved edits opens a notice in the editor,
|
|
1325
|
+
"This file changed outside the editor." (announced, `role="alert"`; it leaves the
|
|
1326
|
+
focus in the text, and `F6` moves it to **Keep mine** and back): **Reload** makes the new baseline the document (one undo step,
|
|
1327
|
+
reported through `onChange`), **Keep mine** (or `Escape` with the focus in the notice) keeps the document
|
|
1328
|
+
and diffs it against the new baseline. Without unsaved edits, or when the new
|
|
1329
|
+
baseline is the document or a text the editor sent (`onChange`, `onSave`: a
|
|
1330
|
+
save coming back while the user typed on), it is taken silently. A new
|
|
1331
|
+
`value` keeps the caret and the scroll position.
|
|
1332
|
+
|
|
1333
|
+
## Several documents
|
|
1334
|
+
|
|
1335
|
+
`ConfigDocuments` shows several files, a main config and its drop-ins, as
|
|
1336
|
+
VS Code-style tabs over one editor per document, each with its own language
|
|
1337
|
+
(from `fileName` unless given, registered languages included, as
|
|
1338
|
+
`languageForFile` reads it; a file no language claims opens in the default
|
|
1339
|
+
language, with a console warning), baseline, read-only state, `editAs`,
|
|
1340
|
+
schema (documents with the same schema text share one compiled schema; one
|
|
1341
|
+
that does not compile throws, as it does for a `ConfigEditor`) and,
|
|
1342
|
+
optionally, settings, host problems and read-only fields.
|
|
1343
|
+
|
|
1344
|
+
```js
|
|
1345
|
+
import { ConfigDocuments, loadConfigEditor } from "@pngwasi/config-editor";
|
|
1346
|
+
|
|
1347
|
+
await loadConfigEditor();
|
|
1348
|
+
let files = [
|
|
1349
|
+
// The main config stays open: no close button.
|
|
1350
|
+
{
|
|
1351
|
+
id: "main",
|
|
1352
|
+
fileName: "config.yaml",
|
|
1353
|
+
value: mainText,
|
|
1354
|
+
schema,
|
|
1355
|
+
closable: false,
|
|
1356
|
+
},
|
|
1357
|
+
{ id: "limits", fileName: "conf.d/limits.toml", value: limitsText, schema },
|
|
1358
|
+
{
|
|
1359
|
+
id: "clients",
|
|
1360
|
+
fileName: "conf.d/clients.json",
|
|
1361
|
+
value: clientsText,
|
|
1362
|
+
schema,
|
|
1363
|
+
readOnly: true,
|
|
1364
|
+
},
|
|
1365
|
+
];
|
|
1366
|
+
const update = (id, change) => {
|
|
1367
|
+
files = files.map((file) => (file.id === id ? { ...file, ...change } : file));
|
|
1368
|
+
view.update({ documents: files });
|
|
1369
|
+
};
|
|
1370
|
+
const view = new ConfigDocuments(document.getElementById("files"), {
|
|
1371
|
+
documents: files,
|
|
1372
|
+
onChange: (id, value) => update(id, { value }),
|
|
1373
|
+
onSave: async (id, value, language) => {
|
|
1374
|
+
await putFile(id, value);
|
|
1375
|
+
update(id, { baseline: value }); // nothing unsaved any more
|
|
1376
|
+
},
|
|
1377
|
+
onClose: ({ id, dirty }) => {
|
|
1378
|
+
if (dirty && !confirm(`Discard unsaved changes to ${id}?`)) return;
|
|
1379
|
+
files = files.filter((file) => file.id !== id);
|
|
1380
|
+
view.update({ documents: files });
|
|
1381
|
+
},
|
|
1382
|
+
// The "+" after the tabs: you decide what a new file is.
|
|
1383
|
+
onAdd: () => {
|
|
1384
|
+
files = [...files, newDropIn(files)];
|
|
1385
|
+
view.update({ documents: files });
|
|
1386
|
+
},
|
|
1387
|
+
onSelect: (id) => console.log("showing", id),
|
|
1388
|
+
});
|
|
1389
|
+
view.saveAll(); // saves the dirty documents; returns their ids
|
|
1390
|
+
view.select("limits"); // shows it and focuses its editor; false for an id not listed
|
|
1391
|
+
view.activeId; // "limits"
|
|
1392
|
+
view.isDirty("main");
|
|
1393
|
+
```
|
|
1394
|
+
|
|
1395
|
+
- You own the list: `update({ documents })` adds, removes, renames and reorders. A
|
|
1396
|
+
document keeps its editor while its `id` stays listed (a new `value`,
|
|
1397
|
+
`baseline`, `fileName`, `readOnly` or `editAs` updates it in place; a new
|
|
1398
|
+
`language` or `schema` mounts a new editor). Handing the whole list back
|
|
1399
|
+
after every edit is cheap: a `value`, `baseline` or `schema` that is the
|
|
1400
|
+
same string as last time (the one `onChange` gave you included) is not
|
|
1401
|
+
read again, so only the edited document costs anything. A listed `value`
|
|
1402
|
+
always applies (a discard, a reload); one that is the document already
|
|
1403
|
+
changes nothing. A host that lists every `onChange` text back late, in
|
|
1404
|
+
any order (a store that re-renders after a delay), creates the view with
|
|
1405
|
+
`echoes: true`: a document's `value` its editor gave that has not come
|
|
1406
|
+
back yet is then its echo and keeps what the editor holds, as in
|
|
1407
|
+
[Hosts that echo](#hosts-that-echo) (the ranges listed with it are moved
|
|
1408
|
+
to the document; a `value` listed as it was listed last is no news, as
|
|
1409
|
+
an unchanged prop); `view.replaceValue(id, text)` goes back to such a
|
|
1410
|
+
text (list the document with it from then on; `false` for an id not
|
|
1411
|
+
listed or a text it holds already); it changes only that document, the others keep their edits.
|
|
1412
|
+
A document's `readOnlyRanges` are read in the `value` listed with it, as
|
|
1413
|
+
`ConfigEditor`'s `update({ value, readOnlyRanges })` reads them: ranges
|
|
1414
|
+
past that text's end that fit the text the last ones came with (the
|
|
1415
|
+
ranges you kept listing after a `replaceValue`) are read there and moved.
|
|
1416
|
+
Ranges that fit neither hold no other document back: the rest of the
|
|
1417
|
+
list applies, that document keeps the locks it had (carried into its new
|
|
1418
|
+
text; a document listed for the first time is locked whole), and
|
|
1419
|
+
`update` then throws naming it (`documents[0].readOnlyRanges[0]: …`).
|
|
1420
|
+
- `update` and `replaceValue` (on both classes) first apply input the
|
|
1421
|
+
browser sent in this task, which calls `onChange`: what you set from
|
|
1422
|
+
there (a list, a value, locks, callbacks) is newer than the call that
|
|
1423
|
+
started, and that call leaves those keys as you set them, applying only
|
|
1424
|
+
its others.
|
|
1425
|
+
- `onProblems(id, problems)` gives each document's editor's own problems
|
|
1426
|
+
(as `ConfigEditor`'s `onProblems`): once its editor mounts (when the
|
|
1427
|
+
document is first shown, or at once when it is listed with
|
|
1428
|
+
`editAsText`), then each time they change.
|
|
1429
|
+
- Nothing closes by itself: `onClose({ id, dirty })` asks you (close button,
|
|
1430
|
+
middle click, `Delete` on a tab). Only closable documents ask: a document
|
|
1431
|
+
with `closable: false` (switches live) stays open, with no close button,
|
|
1432
|
+
and a middle click or `Delete` on its tab does nothing. Without `onClose`,
|
|
1433
|
+
no tab has a close button.
|
|
1434
|
+
- Adding is yours too: with `onAdd`, a "+" button follows the last tab
|
|
1435
|
+
(outside the tab list, after it in the `Tab` order; named and titled by
|
|
1436
|
+
the `addDocument` text, "New file"). It only calls `onAdd()`: you decide
|
|
1437
|
+
what a new document is and list it, and the document you add in answer is
|
|
1438
|
+
selected, its editor focused without scrolling the page. In answer: the
|
|
1439
|
+
first one added within 5 seconds of the click, before the focus moves to
|
|
1440
|
+
something outside the view (a dialog of yours: select the document with
|
|
1441
|
+
`select(id)` then), before another tab is picked and before the user
|
|
1442
|
+
clicks or types anywhere else in the view (in a document's editor). One
|
|
1443
|
+
added later (by you on your own) is listed, not selected. When the tabs
|
|
1444
|
+
overflow, the "+" stays at the end of the strip. No key adds a document
|
|
1445
|
+
(`Ctrl+T` and `Ctrl+N` belong to the browser). `onClose` and `onAdd`
|
|
1446
|
+
cannot be added by `update` to a view mounted without them.
|
|
1447
|
+
- Switching keeps each document's caret, selection, scroll position, undo
|
|
1448
|
+
history, folds and find widget: an editor mounts the first time its
|
|
1449
|
+
document is shown (at once for a document listed with `editAsText`),
|
|
1450
|
+
then stays (hidden) while it is open. With ten
|
|
1451
|
+
~2000-line documents all shown, the view used about 21 MB of wasm memory
|
|
1452
|
+
(1.5 to 1.9 MB per editor) and 4 MB of JS heap. Closing a document gives
|
|
1453
|
+
its editor's memory back, as `destroy()` does for a `ConfigEditor` (all
|
|
1454
|
+
but under 1 KB).
|
|
1455
|
+
- Keys: `←`/`→`, `Home`/`End` in the tab list (a WAI-ARIA `tablist`),
|
|
1456
|
+
`Enter` into the editor (a typed character goes there too, typed at its
|
|
1457
|
+
caret), `Delete` to close a closable one, `Tab` on to
|
|
1458
|
+
the "+"; `Alt+PageDown`/`Alt+PageUp`
|
|
1459
|
+
switch documents from anywhere in the view (browsers keep `Ctrl+Tab` and
|
|
1460
|
+
`Ctrl+PageDown`). `Ctrl+S` saves the document being edited.
|
|
1461
|
+
- Settings: the options take every [setting](#settings), for all the
|
|
1462
|
+
editors and the tabs (`theme`, `colors` with the `tab-*` tokens, see
|
|
1463
|
+
[Styling](#styling); `styled` injects the stylesheet once for the view);
|
|
1464
|
+
`settings` reads them and `update` switches them live, merging key by
|
|
1465
|
+
key. A document's own
|
|
1466
|
+
`settings` go over them for its editor: the keys it gives replace the
|
|
1467
|
+
view's, the rest follow the view's.
|
|
1468
|
+
- Per document, as on `ConfigEditor`: `hostDiagnostics`, `readOnlyPaths`,
|
|
1469
|
+
`readOnlyRanges` (updated in place by `update({ documents })`; a document
|
|
1470
|
+
listed again with the ranges it had and the text its editor holds keeps
|
|
1471
|
+
them where the editor moved them, as `ConfigEditor`'s `update` does) and
|
|
1472
|
+
`secrets` (read when its editor mounts).
|
|
1473
|
+
- What each document shows: `onEditAsChange(id, language)` says the
|
|
1474
|
+
language on screen, once when its editor mounts, then each time it changes
|
|
1475
|
+
(a switch made, also one that waited until the text could convert; undo
|
|
1476
|
+
or redo across a switch). A switch still waiting changes nothing on screen
|
|
1477
|
+
and is not reported. `onSyncChange(id, inSync)` says whether the text on
|
|
1478
|
+
screen is written back to the document's `value` (as `ConfigEditor`'s
|
|
1479
|
+
`onSyncChange`): once when its editor mounts, then on each change. Neither
|
|
1480
|
+
repeats what it said last.
|
|
1481
|
+
- Asking for a language again: a list with the same `editAs` changes
|
|
1482
|
+
nothing (and frameworks do not send an unchanged prop), so after the user
|
|
1483
|
+
undid a switch, `view.editAs(id, language)` asks for it again (the
|
|
1484
|
+
document's own language goes back; a switch the text cannot make yet
|
|
1485
|
+
waits). Keep the document's `editAs` the same in your list, or the next
|
|
1486
|
+
`update({ documents })` switches back.
|
|
1487
|
+
- Opening from the text the user had: `editAsText` (with `editAs`) opens the
|
|
1488
|
+
document's editor with that text on screen in the `editAs` language, in
|
|
1489
|
+
place of `value` converted: what you kept from `view.editor(id).text`
|
|
1490
|
+
before the view went away. `value` and `baseline` stay yours; the text
|
|
1491
|
+
converts back like an edit, so `onChange` hears it once it converts
|
|
1492
|
+
(comments of `value` kept), and until then `onSyncChange` says `false`.
|
|
1493
|
+
Undo starts at it. The editor of a document listed with it mounts at
|
|
1494
|
+
once, shown or not: the text is an unsaved edit, so `isDirty`, the tab's
|
|
1495
|
+
dot, `onSyncChange`, `save()` and `saveAll()` answer as if it were shown.
|
|
1496
|
+
- A reason for a read-only document: `readOnlyReason` (with `readOnly`,
|
|
1497
|
+
updates live) shows in the tab's tooltip and accessible description, in
|
|
1498
|
+
the "Cannot edit in a read-only editor" notice when the user tries to type
|
|
1499
|
+
and in the text area's accessible description.
|
|
1500
|
+
|
|
1501
|
+
```js
|
|
1502
|
+
const view = new ConfigDocuments(element, {
|
|
1503
|
+
documents: [
|
|
1504
|
+
// Back on the page: the TOML the user had, not valid yet.
|
|
1505
|
+
{
|
|
1506
|
+
id: "main",
|
|
1507
|
+
fileName: "config.yaml",
|
|
1508
|
+
value: saved,
|
|
1509
|
+
editAs: "toml",
|
|
1510
|
+
editAsText: kept,
|
|
1511
|
+
},
|
|
1512
|
+
{
|
|
1513
|
+
id: "clients",
|
|
1514
|
+
fileName: "conf.d/clients.json",
|
|
1515
|
+
value: clients,
|
|
1516
|
+
readOnly: true,
|
|
1517
|
+
readOnlyReason: "Managed by the cluster operator",
|
|
1518
|
+
},
|
|
1519
|
+
],
|
|
1520
|
+
onEditAsChange: (id, language) => showLanguage(id, language),
|
|
1521
|
+
onSyncChange: (id, inSync) => (saveButton.disabled = !inSync),
|
|
1522
|
+
});
|
|
1523
|
+
view.editAs("main", "toml"); // after an undo across the switch: ask again
|
|
1524
|
+
```
|
|
1525
|
+
|
|
1526
|
+
- `editor(id)` returns that document's editor, an
|
|
1527
|
+
[`EditorView`](#instance-members) like a `ConfigEditor` (`null` for an id
|
|
1528
|
+
not listed): its `value` (the host's, then each edit), `settings` (its
|
|
1529
|
+
own over the view's) and `unifiedDiff` against its baseline, paths,
|
|
1530
|
+
folds, `focus`, `save` and `isDirty`. An editor mounts the first time
|
|
1531
|
+
its document is shown (at once with `editAsText`): until then `value`, `text` and `unifiedDiff`
|
|
1532
|
+
answer the document as listed, `settings` and `isDirty` answer too and
|
|
1533
|
+
`save()` sends it, while its paths, folds and `reveal` answer `null` or
|
|
1534
|
+
`false` (`[]` for `foldedLines`). With `editAsText` it answers from that
|
|
1535
|
+
text from the constructor on; a document an `update` lists with it opens
|
|
1536
|
+
once the view renders the new list (its panel is not on the page before),
|
|
1537
|
+
and until then `save()` and `saveAll()` send nothing for it, never the
|
|
1538
|
+
text as listed. Once its document is removed,
|
|
1539
|
+
it stays with it and answers `null` (`value`, `text`, `currentPath`) or
|
|
1540
|
+
`false` (`save()`, `isDirty`, `reveal`, …), also when a new document
|
|
1541
|
+
with the same id is listed: ask `editor(id)` again for that one.
|
|
1542
|
+
- `update(options)` changes the view live, with `ConfigEditor`'s rules
|
|
1543
|
+
(left out or `undefined` stays, `null` removes a callback or returns a
|
|
1544
|
+
setting to its default, every key checked before any applies): the
|
|
1545
|
+
`documents`, `activeId` (shows that document, leaving the focus where it
|
|
1546
|
+
is), the settings and the callbacks. `className`, `label` (the tab
|
|
1547
|
+
list's name) and `echoes` are fixed and throw, and so does an `onClose` for a view
|
|
1548
|
+
created without one (its tabs have no close buttons); `activeId` given to
|
|
1549
|
+
the constructor is the document shown first. An `activeId` not listed
|
|
1550
|
+
throws there, as a wrong option does; `select(id)` is a request and
|
|
1551
|
+
answers `false` for an id not listed. Also `destroy()` and `free()`, as
|
|
1552
|
+
for a `ConfigEditor`: an edit still converting is sent to `onChange` first.
|
|
1553
|
+
|
|
1554
|
+
```js
|
|
1555
|
+
files = files.map((file) =>
|
|
1556
|
+
file.id === "limits"
|
|
1557
|
+
? {
|
|
1558
|
+
...file,
|
|
1559
|
+
settings: { folding: false },
|
|
1560
|
+
readOnlyPaths: ["/limits/max_pending"],
|
|
1561
|
+
}
|
|
1562
|
+
: file,
|
|
1563
|
+
);
|
|
1564
|
+
view.update({ documents: files, showFooter: true }); // every editor; limits keeps folding off
|
|
1565
|
+
view.update({ activeId: "limits" }); // shows it, the focus stays where it is
|
|
1566
|
+
view.editor("main").reveal("/public_address");
|
|
1567
|
+
```
|
|
1568
|
+
|
|
1569
|
+
## Reviewing changes
|
|
1570
|
+
|
|
1571
|
+
The gutter marks added, modified and removed lines against `baseline`; a
|
|
1572
|
+
marker opens the lines before and now with **Revert** (one undo step,
|
|
1573
|
+
reported through `onChange`). For your own review screen:
|
|
1574
|
+
|
|
1575
|
+
```js
|
|
1576
|
+
const editor = new ConfigEditor(element, {
|
|
1577
|
+
value: saved,
|
|
1578
|
+
onChangeSummary: ({ hunks }) => (reviewButton.disabled = hunks === 0),
|
|
1579
|
+
});
|
|
1580
|
+
reviewButton.onclick = () => showPatch(editor.unifiedDiff());
|
|
1581
|
+
// After saving: editor.update({ baseline: editor.value }) clears the changes.
|
|
1582
|
+
```
|
|
1583
|
+
|
|
1584
|
+
The change summary is read live from `onChangeSummary`, or computed for any
|
|
1585
|
+
two texts with the free `changeSummary(baseline, current)` of
|
|
1586
|
+
`@pngwasi/config-editor/tools`; the editor has no method for it, by design.
|
|
1587
|
+
|
|
1588
|
+
## Custom languages
|
|
1589
|
+
|
|
1590
|
+
`registerLanguage` adds a language written in JavaScript. A `.env` file
|
|
1591
|
+
(`KEY=value` lines) needs only `parse`; its `separators` also give it schema
|
|
1592
|
+
completion and hover:
|
|
1593
|
+
|
|
1594
|
+
```js
|
|
1595
|
+
import { registerLanguage, ConfigEditor } from "@pngwasi/config-editor";
|
|
1596
|
+
import { convert } from "@pngwasi/config-editor/tools";
|
|
1597
|
+
|
|
1598
|
+
const env = registerLanguage({
|
|
1599
|
+
label: "ENV", // its name is the label lowercased: "env"
|
|
1600
|
+
icon: "E", // optional, toolbar icon: one or two letters or digits
|
|
1601
|
+
extensions: ["env"], // optional: also names the language (language: "env"), as "yml" does
|
|
1602
|
+
parse(text) {
|
|
1603
|
+
// Return a JSON value, or throw { message, line?, column? }.
|
|
1604
|
+
return Object.fromEntries(
|
|
1605
|
+
text
|
|
1606
|
+
.split("\n")
|
|
1607
|
+
.filter((line) => line.trim() && !line.startsWith("#"))
|
|
1608
|
+
// `KEY=value`: the value is all after the first `=` (it may hold more).
|
|
1609
|
+
.map((line) => [
|
|
1610
|
+
line.slice(0, line.indexOf("=")),
|
|
1611
|
+
line.slice(line.indexOf("=") + 1),
|
|
1612
|
+
]),
|
|
1613
|
+
);
|
|
1614
|
+
},
|
|
1615
|
+
serialize(value) {
|
|
1616
|
+
// Optional: text for a value, for conversion and editAs.
|
|
1617
|
+
return (
|
|
1618
|
+
Object.entries(value)
|
|
1619
|
+
.map(([key, item]) => `${key}=${item}`)
|
|
1620
|
+
.join("\n") + "\n"
|
|
1621
|
+
);
|
|
1622
|
+
},
|
|
1623
|
+
keySpan(text, pointer) {
|
|
1624
|
+
// Optional: { line, startColumn, endColumn } (one-based) of the key at a
|
|
1625
|
+
// JSON pointer, so schema problems are underlined. Without it, or where
|
|
1626
|
+
// it returns null or undefined, a flat language (separators, no
|
|
1627
|
+
// contextAt) finds keys on their lines.
|
|
1628
|
+
return null;
|
|
1629
|
+
},
|
|
1630
|
+
valueSpan(text, pointer) {
|
|
1631
|
+
// Optional, like keySpan for the value; Edit-as saves edit values in
|
|
1632
|
+
// place with it. Without it, a flat language finds values on their
|
|
1633
|
+
// lines, and a list's items on the deeper lines under its key (after
|
|
1634
|
+
// `itemMarker` when declared).
|
|
1635
|
+
return null;
|
|
1636
|
+
},
|
|
1637
|
+
highlight(line) {
|
|
1638
|
+
// Optional: [{ start, end, kind }] ranges of one line, as JavaScript
|
|
1639
|
+
// string indices (what `indexOf` gives); kind is
|
|
1640
|
+
// "key" | "string" | "value" | "literal" | "comment" | "punctuation" |
|
|
1641
|
+
// "reference" (an anchor, an alias) | "interpolation" (`${…}` in a string).
|
|
1642
|
+
},
|
|
1643
|
+
// Optional syntax, as in VS Code's language configuration:
|
|
1644
|
+
comments: { lineComment: "#" }, // Ctrl+/ (a list: the first is written); blockComment: ["/*", "*/"] is unwrapped
|
|
1645
|
+
brackets: [
|
|
1646
|
+
["{", "}"],
|
|
1647
|
+
["[", "]"],
|
|
1648
|
+
], // they auto-close, and Enter between them opens a line
|
|
1649
|
+
separators: ["="], // key renames, Tab through empty values, schema completion and hover
|
|
1650
|
+
});
|
|
1651
|
+
|
|
1652
|
+
new ConfigEditor(element, { language: env, schema });
|
|
1653
|
+
convert("env", "listen=7835\n", "yaml").text; // 'listen: "7835"\n'
|
|
1654
|
+
```
|
|
1655
|
+
|
|
1656
|
+
A registered language gets schema validation (placed with `keySpan` and
|
|
1657
|
+
`valueSpan`), conversion to and from every other language, and Edit-as;
|
|
1658
|
+
`comments`, `brackets` and `separators` add comment toggling,
|
|
1659
|
+
auto-closed brackets and bracket-aware Enter, and key/value editing. A language without `serialize`
|
|
1660
|
+
reads documents but cannot write them, so it is never edited as another
|
|
1661
|
+
language nor another as it: `editAs` either way throws
|
|
1662
|
+
`editAs: <label> cannot write documents`. `serialize` is given plain data:
|
|
1663
|
+
an infinity or `NaN` from another language as the text `inf`, `-inf` or
|
|
1664
|
+
`nan` (a conversion lists it as a loss), and an integer past 2^53 as a
|
|
1665
|
+
`bigint`, exact.
|
|
1666
|
+
|
|
1667
|
+
Read-only fields (`readOnly` in the schema, `readOnlyPaths`) hold in every
|
|
1668
|
+
registered language. Where the language says where a field is written
|
|
1669
|
+
(`keySpan` / `valueSpan`, or a flat language's lines), its value is muted,
|
|
1670
|
+
the gutter shows a lock, and an edit on it is refused as it is made. A
|
|
1671
|
+
language that cannot say still keeps the field: an edit after which the text
|
|
1672
|
+
parses with the field's value changed is refused (while the text does not
|
|
1673
|
+
parse, the edit that makes it parse again is checked). Secret placeholders
|
|
1674
|
+
are found by their text and need nothing from the language. Built-in names cannot be
|
|
1675
|
+
replaced, and a registered language cannot take another's name or extension
|
|
1676
|
+
(`registerLanguage` throws); registering the same label again replaces its
|
|
1677
|
+
definition, in the editors already open too, and takes no more memory (a
|
|
1678
|
+
component may register its language each time it mounts). Its name is the label lowercased (`"Énv"` → `"énv"`).
|
|
1679
|
+
|
|
1680
|
+
### Schema completion and hover
|
|
1681
|
+
|
|
1682
|
+
Suggestions and hover docs run through the same engine as the built-in
|
|
1683
|
+
languages', in one of two ways.
|
|
1684
|
+
|
|
1685
|
+
**Languages known by their syntax (no callbacks).** A language with one
|
|
1686
|
+
`KEY=value` entry per line, like the `.env` one above, gets them from its
|
|
1687
|
+
`separators` with no more code, and from the syntax it declares for values
|
|
1688
|
+
written on one line (`mapBrackets`, `listBrackets`, `itemSeparator`,
|
|
1689
|
+
`itemMarker`, see below):
|
|
1690
|
+
|
|
1691
|
+
- before a line's first separator, the schema's top-level keys are
|
|
1692
|
+
suggested, those already written on other lines left out;
|
|
1693
|
+
- after it, the key's values (an `enum`, `true` / `false`, a `const`), a
|
|
1694
|
+
string written bare when it reads back as written (`LOG_LEVEL=debug`);
|
|
1695
|
+
- inside a map written on one line (`server: <host: 'a'; |>`), the map's
|
|
1696
|
+
keys and values; inside a list, its items; on a line starting with
|
|
1697
|
+
`itemMarker` below a key with no value, the keys of that list's item;
|
|
1698
|
+
- accepting a key writes the entry as your `serialize` writes it, with the
|
|
1699
|
+
value the schema gives (a default, required children, a list's items),
|
|
1700
|
+
the caret at the first value left to type, and `Tab` to the next: `KEY=`,
|
|
1701
|
+
or with the spacing `writtenSeparator` gives (`writtenSeparator: ": "`
|
|
1702
|
+
writes `key: `); a key your `parse` would not read back is not suggested;
|
|
1703
|
+
- typed in front of a key (`LOG|PORT=80`), a new entry goes before it, on a
|
|
1704
|
+
line of its own; a suggestion completing the key (`PO|RTX=80`) renames
|
|
1705
|
+
it, keeping its value;
|
|
1706
|
+
- hovering a key shows its schema docs;
|
|
1707
|
+
- nothing is suggested on a line comment.
|
|
1708
|
+
|
|
1709
|
+
**Nested languages (callbacks).** A language with objects inside objects
|
|
1710
|
+
says where the caret is with three optional callbacks. Each one replaces its
|
|
1711
|
+
part of the default above; the rest (the schema at a path, filtering and
|
|
1712
|
+
ranking, the popup, value docs, required fields, `oneOf` choices) is the
|
|
1713
|
+
editor's, as for the built-in languages.
|
|
1714
|
+
|
|
1715
|
+
| Callback | When it is called | Returns | `null` / missing |
|
|
1716
|
+
| ------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
1717
|
+
| `contextAt(text, offset)` | As suggestions open or update, and to place a hovered key; `offset` is the caret's string index | `{ path, at, prefix }`. `at: "key"`: a key is typed in the object at `path`. `at: "value"`: the caret is in the value of the key that ends `path` (a path ending in an index: an array item). `prefix`: what is typed before the caret, which suggestions filter by and replace | `null`: nothing to suggest there. Missing: the default above |
|
|
1718
|
+
| `insertKey(key, kind)` | For each key suggested; `kind` is what the schema expects as its value: `"scalar"`, `"object"` or `"array"` | `{ text, caret }`: the text written, and the caret's string index in it. Lines after the first are indented as the caret's line | `null`: the key is not suggested. Missing: the entry as `serialize` writes it |
|
|
1719
|
+
| `keyAt(text, offset)` | As the mouse rests on the text; `offset` is the string index under it | `{ key, path, start }`: the key's name, its full path (ending with it), and the string index where it starts | `null`: no key there. Missing: the key before the line's first separator |
|
|
1720
|
+
|
|
1721
|
+
Paths are keys and array indices, as `["server", "tls"]`. Keys already
|
|
1722
|
+
written in the object at the caret are left out: the editor reads the
|
|
1723
|
+
document through `parse` without the caret's line (while that does not
|
|
1724
|
+
parse, none are left out). Values are written as JSON. A result of the wrong
|
|
1725
|
+
shape is warned about in the console (once) and read as `null`; a callback
|
|
1726
|
+
that throws is logged and read as `null` too.
|
|
1727
|
+
|
|
1728
|
+
<details>
|
|
1729
|
+
<summary>A sketch: completion and hover for an HJSON-like language</summary>
|
|
1730
|
+
|
|
1731
|
+
This is what lets formats the editor does not ship (HJSON, KDL, UCL, …) get
|
|
1732
|
+
suggestions: `parse` comes from the host's own parser, and the callbacks
|
|
1733
|
+
from what it knows of positions. A sketch for an HJSON-like language
|
|
1734
|
+
(`key: value` lines, `key: {` … `}` blocks), where `scan(text)` stands for
|
|
1735
|
+
the host's line scanner (for each line: the keys of the objects open there,
|
|
1736
|
+
its key and the key's column):
|
|
1737
|
+
|
|
1738
|
+
```js
|
|
1739
|
+
registerLanguage({
|
|
1740
|
+
label: "HJSON",
|
|
1741
|
+
parse: (text) => Hjson.parse(text),
|
|
1742
|
+
separators: [":"],
|
|
1743
|
+
writtenSeparator: ": ",
|
|
1744
|
+
contextAt(text, offset) {
|
|
1745
|
+
const line = scan(text).at(text.slice(0, offset).split("\n").length - 1);
|
|
1746
|
+
const before = text.slice(text.lastIndexOf("\n", offset - 1) + 1, offset);
|
|
1747
|
+
const colon = before.indexOf(":");
|
|
1748
|
+
if (colon < 0) return { path: line.path, at: "key", prefix: before.trim() };
|
|
1749
|
+
const key = before.slice(0, colon).trim();
|
|
1750
|
+
return {
|
|
1751
|
+
path: [...line.path, key],
|
|
1752
|
+
at: "value",
|
|
1753
|
+
prefix: before.slice(colon + 1).trimStart(),
|
|
1754
|
+
};
|
|
1755
|
+
},
|
|
1756
|
+
insertKey(key, kind) {
|
|
1757
|
+
if (kind === "object")
|
|
1758
|
+
return { text: `${key}: {\n \n}`, caret: key.length + 6 };
|
|
1759
|
+
return { text: `${key}: `, caret: key.length + 2 };
|
|
1760
|
+
},
|
|
1761
|
+
keyAt(text, offset) {
|
|
1762
|
+
const line = scan(text).at(text.slice(0, offset).split("\n").length - 1);
|
|
1763
|
+
const start = text.lastIndexOf("\n", offset - 1) + 1 + line.keyColumn;
|
|
1764
|
+
if (!line.key || offset < start || offset >= start + line.key.length)
|
|
1765
|
+
return null;
|
|
1766
|
+
return { key: line.key, path: [...line.path, line.key], start };
|
|
1767
|
+
},
|
|
1768
|
+
});
|
|
1769
|
+
```
|
|
1770
|
+
|
|
1771
|
+
</details>
|
|
1772
|
+
|
|
1773
|
+
### Strings and comments over lines
|
|
1774
|
+
|
|
1775
|
+
`highlight` colors one line at a time. For what spans lines (HJSON's `'''`
|
|
1776
|
+
strings, `/* */` comments), `multilineRanges(text)` returns
|
|
1777
|
+
`[{ start, end, kind }]`: string indices, and `kind` `"string"` or
|
|
1778
|
+
`"comment"`. The lines after a range's first are colored as its kind up to
|
|
1779
|
+
`end`, and the rest of its last line by `highlight`; nothing is suggested
|
|
1780
|
+
inside, a string's lines stay text for Enter, and a line comment marker
|
|
1781
|
+
inside a range starts no comment. On one line, a string in `"…"` or `'…'`
|
|
1782
|
+
and a comment after one of your `comments` markers are known without it:
|
|
1783
|
+
there too nothing is suggested in a comment, and quotes and brackets do
|
|
1784
|
+
not pair in a string or a comment.
|
|
1785
|
+
|
|
1786
|
+
```js
|
|
1787
|
+
multilineRanges(text) {
|
|
1788
|
+
return [...text.matchAll(/'''[\s\S]*?(?:'''|$)|\/\*[\s\S]*?(?:\*\/|$)/g)].map((match) => ({
|
|
1789
|
+
start: match.index,
|
|
1790
|
+
end: match.index + match[0].length,
|
|
1791
|
+
kind: match[0].startsWith("/*") ? "comment" : "string",
|
|
1792
|
+
}));
|
|
1793
|
+
},
|
|
1794
|
+
```
|
|
1795
|
+
|
|
1796
|
+
### Edit-as with a custom language
|
|
1797
|
+
|
|
1798
|
+
<details>
|
|
1799
|
+
<summary>How a save edits the stored text in place</summary>
|
|
1800
|
+
|
|
1801
|
+
A document stored in a custom language and edited as another (`editAs`)
|
|
1802
|
+
is saved back by editing its own text, not by writing it anew: a changed
|
|
1803
|
+
value is rewritten where `valueSpan` places it, and a key added, removed or
|
|
1804
|
+
renamed changes just its lines (compared line by line with what `serialize`
|
|
1805
|
+
writes, so this works without spans too). Comments, blank lines and the
|
|
1806
|
+
entries left alone stay as written. The whole document comes from
|
|
1807
|
+
`serialize` only when the stored text did not parse before the edit, or no
|
|
1808
|
+
such patch reads back (through `parse`) as the edited data. Highlighting
|
|
1809
|
+
stays per line (`highlight`), with `multilineRanges` for what spans lines.
|
|
1810
|
+
The save reads your syntax only from what you declare (`comments`,
|
|
1811
|
+
`brackets`, `separators`, strings in `"…"` or `'…'`): no built-in
|
|
1812
|
+
language's characters are assumed. Declare how maps and lists are written
|
|
1813
|
+
on one line, and a save edits them where they are, keeping the line's
|
|
1814
|
+
comment and the spacing around them (a list keeps its own spacing too; a
|
|
1815
|
+
changed map is written by `serialize`, with its spacing):
|
|
1816
|
+
|
|
1817
|
+
| Member | Example | Says |
|
|
1818
|
+
| ------------------ | ------------ | ------------------------------------------------------------------------------------- |
|
|
1819
|
+
| `mapBrackets` | `["{", "}"]` | the brackets around a map written on one line |
|
|
1820
|
+
| `listBrackets` | `["[", "]"]` | the brackets around a list written on one line |
|
|
1821
|
+
| `itemSeparator` | `","` | what separates their items, one character |
|
|
1822
|
+
| `itemMarker` | `"-"` | what starts a list item on lines of its own: a save moves it with its lines, comments |
|
|
1823
|
+
| `literalQuotes` | `["'"]` | the quotes (of `"` and `'`) a backslash does not escape in |
|
|
1824
|
+
| `writtenSeparator` | `": "` | one of `separators` with the spacing a new entry writes |
|
|
1825
|
+
|
|
1826
|
+
A member of the wrong shape makes `registerLanguage` throw.
|
|
1827
|
+
|
|
1828
|
+
</details>
|
|
1829
|
+
|
|
1830
|
+
## Themes
|
|
1831
|
+
|
|
1832
|
+
The `theme` setting takes a slug; `themes()` returns them all, each with
|
|
1833
|
+
its display name and whether it is dark.
|
|
1834
|
+
|
|
1835
|
+
<details>
|
|
1836
|
+
<summary>The eleven themes</summary>
|
|
1837
|
+
|
|
1838
|
+
| Slug | Name | Look |
|
|
1839
|
+
| ----------------- | -------------------------- | ----- |
|
|
1840
|
+
| `vscode-dark` | VS Code Dark (the default) | dark |
|
|
1841
|
+
| `vscode-light` | VS Code Light | light |
|
|
1842
|
+
| `obsidian` | Obsidian Dark | dark |
|
|
1843
|
+
| `obsidian-light` | Obsidian Light | light |
|
|
1844
|
+
| `dracula` | Dracula | dark |
|
|
1845
|
+
| `nord` | Nord | dark |
|
|
1846
|
+
| `atom-one-dark` | Atom One Dark | dark |
|
|
1847
|
+
| `github-light` | GitHub Light | light |
|
|
1848
|
+
| `github-dark` | GitHub Dark | dark |
|
|
1849
|
+
| `solarized-light` | Solarized Light | light |
|
|
1850
|
+
| `vira-inspired` | Vira-inspired (original) | dark |
|
|
1851
|
+
|
|
1852
|
+
</details>
|
|
1853
|
+
|
|
1854
|
+
## Styling
|
|
1855
|
+
|
|
1856
|
+
The editor injects its own stylesheet: one `<style>` at the end of the
|
|
1857
|
+
page's `<head>` (or in the shadow root the editor is in), shared by every
|
|
1858
|
+
editor and documents view there and removed with the last. Your page's
|
|
1859
|
+
rules for bare elements, attributes or every element (a CSS framework's
|
|
1860
|
+
`input`, `div`, `[type='text']` or `*` rules, loaded before the editor or
|
|
1861
|
+
after) never reach what it draws: each element inside starts from the
|
|
1862
|
+
browser's own styles, and its rules for them carry an id's weight. Nor do
|
|
1863
|
+
the text properties your page sets on `body` or on the editor's element
|
|
1864
|
+
(`text-align: center`, an underline, letter spacing, a tab size): its
|
|
1865
|
+
roots set each to its initial value, nor a bare element rule's padding or
|
|
1866
|
+
margin (`div { padding: 1rem }`) to the roots' own box. Style the editor
|
|
1867
|
+
through its roots (`.config-editor`, `.config-editor-documents`; a rule of
|
|
1868
|
+
yours later in the page wins over the preset's at equal specificity) and its
|
|
1869
|
+
color variables. The roots' text properties (`letter-spacing`,
|
|
1870
|
+
`text-transform`, `text-align`, `word-spacing`, `tab-size` and the like) are
|
|
1871
|
+
fixed by the editor, so the drawn text stays over the text area's: a rule of
|
|
1872
|
+
yours setting them on a root has no effect; the font size and line height
|
|
1873
|
+
go through their variables. Every theme color is a CSS variable on the `.config-editor` root, and the
|
|
1874
|
+
bundled themes set them with zero specificity, so a plain rule in your
|
|
1875
|
+
stylesheet overrides any theme, wherever it sits. Set the `--config-editor-*`
|
|
1876
|
+
variables (colors, `--config-editor-font-size`, `--config-editor-line-height`)
|
|
1877
|
+
on the editor's root: `.config-editor`, or your `className`, which goes on
|
|
1878
|
+
it. On `body`, `html` or the element you mount the editor in they have no
|
|
1879
|
+
effect, as the root sets each itself. The height ones
|
|
1880
|
+
(`--config-editor-height`, `--config-editor-min-height`,
|
|
1881
|
+
`--config-editor-max-height`) the root does not set, so they inherit: on the
|
|
1882
|
+
root or on any element above it. The shield covers your page's bare-element rules, not rules marked
|
|
1883
|
+
`!important` and not rules that target the editor's inner `config-editor__*`
|
|
1884
|
+
classes: those are your choice.
|
|
1885
|
+
|
|
1886
|
+
```css
|
|
1887
|
+
.config-editor {
|
|
1888
|
+
--config-editor-bg: #101418;
|
|
1889
|
+
--config-editor-key: #ffcc66;
|
|
1890
|
+
}
|
|
1891
|
+
```
|
|
1892
|
+
|
|
1893
|
+
With `styled: false` the editor injects nothing, and its markup
|
|
1894
|
+
(`config-editor__*` classes) is yours to style; the package ships the preset
|
|
1895
|
+
as `@pngwasi/config-editor/preset.css` to serve or adapt (`presetCss()`
|
|
1896
|
+
returns the same text).
|
|
1897
|
+
|
|
1898
|
+
### Size
|
|
1899
|
+
|
|
1900
|
+
The editor sizes itself, not by its element's height: its text area grows
|
|
1901
|
+
with the text from `--config-editor-min-height` (240px, less in a window too
|
|
1902
|
+
short for it) to `--config-editor-max-height` (80% of the window, less in a
|
|
1903
|
+
short one), then scrolls; the toolbar, tab bar and footer come on top.
|
|
1904
|
+
`--config-editor-height` (a length, such as `400px`) fixes the text area's
|
|
1905
|
+
height. To fill an element of a set height, give the editor `height: 100%`:
|
|
1906
|
+
the text area takes what the toolbar and footer leave, however short or tall
|
|
1907
|
+
(neither the minimum nor the 80% applies, unless you set the custom
|
|
1908
|
+
property).
|
|
1909
|
+
|
|
1910
|
+
```css
|
|
1911
|
+
#config {
|
|
1912
|
+
height: 60vh;
|
|
1913
|
+
}
|
|
1914
|
+
#config .config-editor {
|
|
1915
|
+
height: 100%;
|
|
1916
|
+
}
|
|
1917
|
+
/* Or a fixed text area: */
|
|
1918
|
+
.config-editor {
|
|
1919
|
+
--config-editor-height: 400px;
|
|
1920
|
+
}
|
|
1921
|
+
```
|
|
1922
|
+
|
|
1923
|
+
`ConfigDocuments` sizes itself the same way: the tab strip, then the shown
|
|
1924
|
+
editor, as tall as its text. To fill an element of a set height, give the
|
|
1925
|
+
view `height: 100%`: the strip keeps its height and the shown editor (its
|
|
1926
|
+
text area, between its toolbar and footer) takes the rest, with one
|
|
1927
|
+
document or many.
|
|
1928
|
+
|
|
1929
|
+
```css
|
|
1930
|
+
#files {
|
|
1931
|
+
height: 60vh;
|
|
1932
|
+
}
|
|
1933
|
+
#files .config-editor-documents {
|
|
1934
|
+
height: 100%;
|
|
1935
|
+
}
|
|
1936
|
+
```
|
|
1937
|
+
|
|
1938
|
+
### Strict Content-Security-Policy
|
|
1939
|
+
|
|
1940
|
+
The editor runs under a policy without `'unsafe-inline'`:
|
|
1941
|
+
|
|
1942
|
+
```text
|
|
1943
|
+
Content-Security-Policy: default-src 'self'; style-src 'self'; script-src 'self' 'wasm-unsafe-eval'
|
|
1944
|
+
```
|
|
1945
|
+
|
|
1946
|
+
- Set `styled: false` (on `ConfigEditor`, or once on `ConfigDocuments`): the
|
|
1947
|
+
injected `<style>` is inline, so the policy refuses it.
|
|
1948
|
+
- Serve `preset.css` as a file and link it: one file with the base styles,
|
|
1949
|
+
every theme and the tabs of `ConfigDocuments`, so themes and `colors`
|
|
1950
|
+
switch as they do with the injected stylesheet. With a bundler, import it
|
|
1951
|
+
(`import "@pngwasi/config-editor/preset.css";`) so it lands in your CSS
|
|
1952
|
+
bundle; without one, copy `node_modules/@pngwasi/config-editor/preset.css`
|
|
1953
|
+
next to your page and add `<link rel="stylesheet" href="/preset.css">`.
|
|
1954
|
+
- `'wasm-unsafe-eval'` lets the page compile the WebAssembly; nothing else
|
|
1955
|
+
in the editor evaluates code.
|
|
1956
|
+
|
|
1957
|
+
Everything else holds as it is: the editor sets positions, sizes and
|
|
1958
|
+
`colors` through the CSSOM (`style.setProperty`), which the policy allows,
|
|
1959
|
+
never as `style` attributes, and its icons are inline SVG, not `data:`
|
|
1960
|
+
images. The React, Vue and Svelte components work the same way (with Vue,
|
|
1961
|
+
write render functions or precompiled templates: compiling a template in the
|
|
1962
|
+
browser needs `'unsafe-eval'`). An end-to-end test runs every feature under
|
|
1963
|
+
this policy, in plain JavaScript and in each framework.
|
|
1964
|
+
|
|
1965
|
+
<details>
|
|
1966
|
+
<summary>The color tokens: the colors setting, the diff, the footer counts and the tabs</summary>
|
|
1967
|
+
|
|
1968
|
+
The `colors` setting sets the variables per editor, by token: its type is
|
|
1969
|
+
`ThemeColorMap`, keyed by `ThemeColorToken` (both exported), which lists
|
|
1970
|
+
every token. The diff markers use `added`,
|
|
1971
|
+
`modified` and `removed` (which follows `error` unless set), and the
|
|
1972
|
+
footer's change count `status-changes`; its problem counts `status-error`,
|
|
1973
|
+
`status-warning`, `status-info` and `status-hint`, each in its own color.
|
|
1974
|
+
|
|
1975
|
+
The tabs of `ConfigDocuments` use `tab-bar` (the strip), `tab-bg` /
|
|
1976
|
+
`tab-active-bg`, `tab-text` / `tab-active-text`, `tab-border`,
|
|
1977
|
+
`tab-active-border` (the line over the active tab) and `tab-dirty` (the
|
|
1978
|
+
unsaved-changes dot); they follow `panel`, `bg`, `muted`, `text`, `border`
|
|
1979
|
+
and `accent` unless set, as variables on the `.config-editor-documents` root
|
|
1980
|
+
or through its `colors` setting.
|
|
1981
|
+
|
|
1982
|
+
</details>
|
|
1983
|
+
|
|
1984
|
+
## License
|
|
1985
|
+
|
|
1986
|
+
MIT. See [LICENSE](LICENSE).
|