@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/README.md CHANGED
@@ -1,3 +1,1986 @@
1
- # Temporary Holding Version
1
+ # Config Editor for JavaScript
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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).