El editor para páginas web

<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">
Receta (com.example.cocina): Tortitas
	Raciones: cuatro
	Dificultad: Fácil
</textarea>

<script>
    const plantilla = `
Template (@stxt.template): com.example.cocina
	Structure >>
		Receta (com.example.cocina):
			Raciones: (1) NATURAL
			Dificultad: (?) ENUM [Fácil, Media, Difícil]
`;

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

En este ejemplo tenemos:

• El documento: el texto del <textarea>.
• La gramática: una plantilla, pasada como texto en grammars.
• Un error: Raciones: cuatro queda subrayado, porque la plantilla pide un NATURAL.

Es el editor del playground, publicado como biblioteca. Usa la biblioteca TypeScript @stxt-lang/core y no lleva gramática propia del lenguaje: los errores y sus códigos son los mismos que en la línea de comandos, la extensión de VS Code y las bibliotecas.

Qué hace

• Coloreado: sale del parseo del documento. Los bloques que la gramática declara MARKDOWN se colorean como Markdown.
• Errores durante la edición: de sintaxis y de validación contra las gramáticas.
• Autocompletado: al escribir o con Ctrl+Espacio. Ofrece los nodos que la gramática permite en ese punto y los valores de un ENUM.
• Hover: sobre un nodo, lo que el parser y su gramática dicen de él.
• Tabulador: inserta un tabulador o cuatro espacios. Al cambiar de uno a otro se reindenta el documento.
• Formularios: el <textarea> queda oculto y sincronizado, y su formulario sigue enviando el texto.

Instalación

La versión actual es la 0.1.0. La API puede cambiar antes de la 1.0.

Con <script> no hay instalación. El paquete incluye los ficheros listos para una página, minificados, y los sirve cualquier CDN de paquetes npm. Están en https://cdn.jsdelivr.net/npm/@stxt-lang/[email protected]/:

Con un bundler:

npm install @stxt-lang/editor

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

El paquete es un módulo ES con declaraciones de tipos. CodeMirror 6 y @stxt-lang/core son dependencias y no van dentro: una página que ya usa CodeMirror carga una sola copia.

Crear un editor

Las dos devuelven un Editor. Ninguna opción es obligatoria:

Una gramática escrita dentro del propio documento también vale.

El editor

Con el documento y la plantilla del principio:

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

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

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

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

editor.setIndent('spaces');   // reindenta el documento con cuatro espacios
editor.getValue();            // "Receta (com.example.cocina): Tortitas\n    Raciones: cuatro\n..."

Un diagnóstico tiene cinco campos:

Para más de un documento por vista, o para otra disposición, el paquete exporta también las piezas del editor:

• Analyzer: parsea y valida un conjunto de documentos. No usa el DOM ni CodeMirror.
• createStxtEditor, createStxtExtensions: las extensiones de CodeMirror.
• setTokensEffect, toCmDiagnostics: llevan un análisis a una vista.

Coloreado estático

Para las páginas que muestran STXT y no lo editan hay un coloreado sin 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">Receta (com.example.cocina): Tortitas
	Raciones: 4</code></pre>

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

La única opción es grammars: con ellas, los bloques MARKDOWN se colorean como Markdown. Con un bundler se importa de @stxt-lang/editor/highlight:

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

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

Temas

Los colores son propiedades CSS de .stxt-editor (el editor) y de .stxt-highlight (el coloreado estático):

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

.stxt-editor {
    height: 22rem;
}

Sin altura, el editor crece con el texto. Con altura, tiene scroll.

Los valores por defecto son la paleta de este sitio. El código y los cambios de cada versión están en el repositorio.