# AURA für VS Code

<p align="center"><img src="media/icon.png" alt="AURA" width="96"></p>

Syntax-Highlighting, Formatter, Code-Vervollständigung und Live-Vorschau für `.aura`-Dateien (siehe `docs/aura.md`). Reines JavaScript, ohne npm-Abhängigkeiten und ohne Build-Schritt.

## Inline-Skripte

Ereignisse können einen Skriptblock enthalten: `onTap: { state.count += 1; }`.
Ohne Angabe gilt JavaScript. `scriptLanguage: "lua"` am Dateianfang wählt Lua.
Der Formatter lässt Skriptinhalte unverändert; die Vorschau führt dieselben Handler
wie das Programm aus. `state` enthält die Properties der jeweiligen Wurzel;
`event.value` enthält den Wert eines Widget-Ereignisses. Mit `emit("name", wert)`
können deklarierte Signale ausgelöst werden.

## Funktionen

- **Highlighting:** Schlüsselwörter, `Dialog`/`Screen`, eingebaute Elementtypen und Komponenten, IDs (`Text { id: title }`), Property-Typen, Signale mit Parametern, Properties (bekannte aus `schema.h` hervorgehoben), `place`-Direktiven mit Zielelement, `on<Signal>`-Handler, `align`/`fill`/`corners`-Werte, Farben (`#rrggbb`, `#aarrggbb`), Zahlen, Strings mit Escapes, Kommentare, Operatoren, Funktionen, `theme.`/`screen.`/`props.` und die reservierten IDs.
- **Formatter** („Format Document“, Shift+Alt+F, auch für eine Auswahl):
  - Einrückung 4 Leerzeichen pro `{`-Ebene (bzw. `editor.tabSize`/`insertSpaces`), Fortsetzungszeilen in offenen `()`/`[]` und mehrzeilige `? :` eine Ebene tiefer,
  - `name: wert`, `, ` in Listen, Leerzeichen um binäre Operatoren, `Typ { id: elementName }`, `component Name : Basis`,
  - keine Leerzeichen am Zeilenende, höchstens eine Leerzeile am Stück, genau ein Zeilenende am Dateiende.
  - Zeilenumbrüche, Strings, Kommentare und Farben bleiben unverändert. In `place:`, `loop:`, `enter:` und `exit:` bleibt `-` so stehen, wie es geschrieben ist (`centerY -20` ist ein Vorzeichen, kein Minus).
  - Jede formatierte Zeile wird erneut tokenisiert und verglichen; weicht sie ab, wird sie nur eingerückt.
- **Vervollständigung** (Ctrl+Space, automatisch nach `.`, und nach `:`/`,`/Leerzeichen dort, wo feste Namen folgen):
  - am Anfang einer Anweisung: die Properties des Elementtyps (gemeinsame + eigene; bei Komponenten deren `property`s und `on<Signal>`), ohne die schon gesetzten; Elementtypen (eingebaute und alle Komponenten der `.aura`-Dateien im selben UI-Baum: dem Ordner der Datei bzw. dem übergeordneten Ordner, solange der noch weitere `.aura`-Dateien enthält, mit Unterordnern) als Snippet; `property`, `signal`, `repeat`, `if`, `else`. In `repeat`/`if` nur Elemente.
  - `place:` die Direktiven, nach `below`/`above`/`rightOf`/… die IDs davor (und `parent`),
  - `theme.` (die Namen meldet die laufende Vorschau; die Erweiterung merkt sie sich je Workspace), `screen.`, `props.`, `id.`/`root.`/`parent.` die Element-Werte,
  - `onTap:`/`on<Signal>:` die Signale des Dialogs bzw. der Komponente (`ignore` bei `onTap`),
  - Werte von `align`, `corners`, `fill` (Image), `true`/`false` bei bool-Properties,
  - in Ausdrücken Funktionen mit Parametern, IDs, Dialog-Argumente, Schleifenvariablen; Typen nach `property` und in `signal name(`.
- **Folding:** Blöcke, mehrzeilige Kommentare, Kommentarblöcke, `// region` … `// endregion`.
- **Fehlerprüfung:** Beim Tippen prüft `aurac --check` den UI-Baum der Datei mit den ungespeicherten Inhalten (Schattenkopie) und zeigt den ersten Fehler als Diagnose. Läuft die Vorschau für den Baum, meldet sie die Fehler selbst (auch fehlende Theme-Werte). Einstellung `aura.check.compiler` (Standard `build/dev/tools/aurac/aurac`).
- **Live-Vorschau:** „AURA: Vorschau öffnen“, `Ctrl+K V`, Vorschau-Icon oder Statusleiste startet `tools/aura-view`. Die Vorschau folgt dem Cursor, zeigt ungespeicherte Änderungen und Diagnosen, unterstützt Klicks, Signale, Play/Pause für Animationen, Komponenten, `preview`-Blöcke, Zustände, `bool`-Properties und Zoom. Der native Viewer verwendet `BasicHost`; Geräte-, Sprach- und Barrierefreiheitsoptionen benötigen einen eigenen Host. Voraussetzung: `cmake --build build/dev --target aura-view`. Die direkte Konfiguration steht unter [Vorschau](preview.md).
- **Farben:** Farbfeld und Farbwähler für `#rrggbb`/`#aarrggbb`, Farbfeld und Hover mit dem Wert für `theme.<Farbe>` (aus der laufenden Vorschau).
- **Gehe zu Definition und Umbenennen:** Komponenten, Datensätze, Dialoge, Screens, IDs, Properties, Zustände und Signale (Details in `docs/aura-view.md`).
- **Icons:** AURA-Logo als Icon der Erweiterung, als Datei-Icon für `.aura` (eigene Fassung für dunkle Themes, sichtbar, wenn das Datei-Icon-Theme Sprach-Icons zulässt) und im Reiter der Vorschau. Quellen: `docs/images/aura-icon.svg` (Icon) und `docs/images/aura-logo.svg` (Logo mit Schriftzug); `media/aura-file-dark.svg` ist das Icon mit hellem innerem Dreieck.

## Installieren

```bash
tools/aura-vscode/scripts/install.sh
```

Packt die Erweiterung als VSIX (ohne `vsce`) und installiert sie mit `code --install-extension`. Danach in VS Code „Developer: Reload Window“ ausführen.

Formatieren beim Speichern (`settings.json`):

```json
"[aura]": {
    "editor.defaultFormatter": "hertz.aura-language",
    "editor.formatOnSave": true
}
```

## Entwickeln

Tests und `generate.js` verwenden derzeit externe Anwendungs-Fixtures. `AURA_APP=<fixture-root>` wählt einen Baum mit `app/ui` und `app/ui/aura-elements.json`; alternativ wird das übergeordnete Verzeichnis des AURA-Checkouts durchsucht. Einige Tests erwarten konkrete Dateien und Teststellen: Ein beliebiger UI-Baum reicht nicht aus, eigene Fixtures benötigen passende Testfälle. `AURAC=<compiler>` überschreibt den Compilerpfad.


- **Tests:** `node tools/aura-vscode/test/completion-test.js` prüft die Vervollständigung an ausgewählten Stellen von Kopien der Repo-Dateien (mit nachgebautem `vscode`-Modul). `node tools/aura-vscode/test/format-test.js` formatiert Kopien der `.aura`-Dateien von `app/ui` (in einem Temp-Verzeichnis) und prüft: idempotent, Repo-Dateien unverändert, verwürfelte Kopien werden wiederhergestellt, `aurac` erzeugt denselben C++-Code. `node tools/aura-vscode/test/navigation-test.js` prüft Gehe zu Definition und Umbenennen. `node tools/aura-vscode/test/check-test.js` prüft die Fehlerprüfung (ungespeicherter Fehler, Korrektur, Übergabe an die Vorschau). Den Compiler suchen beide unter `build/dev/tools/aurac/aurac` (sonst `AURAC=...`).
- **Grammatik und Daten:** `syntaxes/aura.tmLanguage.json` und `data/aura-data.json` (Vervollständigung) werden aus `libs/aura-lang/include/aura/lang/schema.h` und der `aura-elements.json` des Programms erzeugt: `node tools/aura-vscode/scripts/generate.js`. Nach Änderungen am Schema neu erzeugen und neu installieren. Die Theme-Werte kommen nicht von dort, sondern von der laufenden Vorschau.