The editor for web pages

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@stxt-lang/[email protected]/dist/stxt-editor.css">
<script src="https://cdn.jsdelivr.net/npm/@stxt-lang/[email protected]/dist/stxt-editor.js"></script>

<textarea id="doc" name="doc">
Recipe (com.example.cooking): Pancakes
	Serves: four
	Difficulty: Easy
</textarea>

<script>
    const template = `
Template (@stxt.template): com.example.cooking
	Structure >>
		Recipe (com.example.cooking):
			Serves: (1) NATURAL
			Difficulty: (?) ENUM [Easy, Medium, Hard]
`;

    const editor = StxtEditor.fromTextArea(document.getElementById('doc'), {
        grammars: [template],
        onChange: (text, diagnostics) => console.log(diagnostics),
    });
</script>

In this example we have:

• The document: the text of the <textarea>.
• The grammar: a template, passed as text in grammars.
• An error: Serves: four is underlined, because the template asks for a NATURAL.

It is the editor of the playground, published as a library. It uses the TypeScript library @stxt-lang/core and carries no grammar of the language of its own: the errors and their codes are the same as in the command line, the VS Code extension and the libraries.

What it does

• Highlighting: it comes from parsing the document. Blocks the grammar declares as MARKDOWN are highlighted as Markdown.
• Errors while editing: syntax errors, and validation errors against the grammars.
• Completion: while typing or with Ctrl+Space. It offers the nodes the grammar allows at that point and the values of an ENUM.
• Hover: over a node, what the parser and its grammar say about it.
• Tab key: it inserts a tab or four spaces. Switching from one to the other re-indents the document.
• Forms: the <textarea> stays hidden and in sync, and its form still submits the text.

Installation

The current version is 0.1.0. The API may change before 1.0.

With a <script> there is nothing to install. The package carries its files ready for a page, minified, and any CDN of npm packages serves them. They are under https://cdn.jsdelivr.net/npm/@stxt-lang/[email protected]/:

With a bundler:

npm install @stxt-lang/editor

import { fromTextArea } from '@stxt-lang/editor';
import '@stxt-lang/editor/stxt-editor.css';

The package is an ES module with type declarations. CodeMirror 6 and @stxt-lang/core are dependencies and are not bundled: a page that already uses CodeMirror loads a single copy.

Creating an editor

Both return an Editor. No option is required:

A grammar written inside the document itself works too.

The editor

With the document and the template of the beginning:

import { mount } from '@stxt-lang/editor';

const editor = mount(document.getElementById('holder'), {
    value: text,
    grammars: [template],
});

editor.getDiagnostics();
// [{ line: 1, code: "INVALID_VALUE", message: "Serves: Invalid natural (four)",
//    severity: "warning", source: "validation" }]

editor.setValidation(false);
editor.getDiagnostics();      // []

editor.setIndent('spaces');   // re-indents the document with four spaces
editor.getValue();            // "Recipe (com.example.cooking): Pancakes\n    Serves: four\n..."

A diagnostic has five fields:

For more than one document per view, or for another layout, the package also exports the pieces of the editor:

• Analyzer: parses and validates a set of documents. It uses neither the DOM nor CodeMirror.
• createStxtEditor, createStxtExtensions: the CodeMirror extensions.
• setTokensEffect, toCmDiagnostics: they take an analysis to a view.

Static highlighting

For pages that show STXT and do not edit it there is a highlighter without CodeMirror:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@stxt-lang/[email protected]/dist/stxt-editor.css">
<script src="https://cdn.jsdelivr.net/npm/@stxt-lang/[email protected]/dist/stxt-highlight.js"></script>

<pre><code class="language-stxt">Recipe (com.example.cooking): Pancakes
	Serves: 4</code></pre>

<script>
    StxtHighlight.highlightAll();
</script>

The only option is grammars: with them, MARKDOWN blocks are highlighted as Markdown. With a bundler it is imported from @stxt-lang/editor/highlight:

import { highlightText } from '@stxt-lang/editor/highlight';

highlightText('Recipe: Pancakes');
// <span class="stxt-tok-property">Recipe</span><span class="stxt-tok-property">:</span><span class="stxt-tok-string"> Pancakes</span>

Themes

The colours are CSS properties of .stxt-editor (the editor) and of .stxt-highlight (the static highlighting):

.stxt-editor,
.stxt-highlight {
    --stxt-node: #0d5cb6;
    --stxt-value: #d05a80;
    --stxt-comment: #008000;
    --stxt-background: #fff;
}

.stxt-editor {
    height: 22rem;
}

Without a height, the editor grows with the text. With one, it scrolls.

The defaults are the palette of this site. The code and the changes of each version are in the repository.