# AURA for VS Code

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

Syntax highlighting, formatter, code completion, and live preview for `.aura` files (see `docs/aura.md`). Plain JavaScript, with no npm dependencies and no build step.

## Inline scripts

Events may contain a script block: `onTap: { state.count += 1; }`.
JavaScript is the default. `scriptLanguage: "lua"` at the start of the file selects Lua.
The formatter leaves script contents unchanged; the preview executes the same handlers
as the application. `state` contains the properties of the corresponding root;
`event.value` contains a widget event's value. Use `emit("name", value)`
to trigger declared signals.

## Features

- **Highlighting:** Keywords, `Dialog`/`Screen`, built-in element types and components, IDs (`Text { id: title }`), property types, parameterized signals, properties (known properties from `schema.h` are highlighted), `place` directives with a target element, `on<Signal>` handlers, `align`/`fill`/`corners` values, colors (`#rrggbb`, `#aarrggbb`), numbers, strings with escapes, comments, operators, functions, `theme.`/`screen.`/`props.`, and reserved IDs.
- **Formatter** (“Format Document”, Shift+Alt+F, also for a selection):
  - Indentation of 4 spaces per `{` level (or `editor.tabSize`/`insertSpaces`), continuation lines inside open `()`/`[]` and multiline `? :` one level deeper,
  - `name: value`, `, ` in lists, spaces around binary operators, `Type { id: elementName }`, `component Name : Base`,
  - No trailing spaces, at most one consecutive blank line, exactly one newline at the end of the file.
  - Line breaks, strings, comments, and colors remain unchanged. In `place:`, `loop:`, `enter:`, and `exit:`, `-` remains as written (`centerY -20` is a signed value, not subtraction).
  - Each formatted line is tokenized again and compared; if the tokens differ, only its indentation is changed.
- **Completion** (Ctrl+Space, automatically after `.`, and after `:`/`,`/a space where fixed names follow):
  - At the start of a statement: the element type's properties (common + own; for components, their `property` declarations and `on<Signal>` handlers), excluding those already set; element types (built-ins and all components in `.aura` files in the same UI tree: the file's folder, or its parent while that parent contains additional `.aura` files, including subfolders) as snippets; `property`, `signal`, `repeat`, `if`, `else`. Inside `repeat`/`if`, only elements.
  - For `place:`, directives; after `below`/`above`/`rightOf`/… preceding IDs (and `parent`),
  - After `theme.`, names reported by the running preview (cached per workspace); after `screen.`, `props.`, `id.`/`root.`/`parent.`, element values,
  - After `onTap:`/`on<Signal>:`, dialog or component signals (`ignore` for `onTap`),
  - Values for `align`, `corners`, `fill` (Image), `true`/`false` for bool properties,
  - In expressions, functions with parameters, IDs, dialog arguments, loop variables; types after `property` and in `signal name(`.
- **Folding:** Blocks, multiline comments, groups of comments, `// region` … `// endregion`.
- **Error checking:** While typing, `aurac --check` checks the file's UI tree using unsaved content (a shadow copy) and displays the first error as a diagnostic. If the preview is running for that tree, it reports errors itself (including missing theme values). Setting: `aura.check.compiler` (default `build/dev/tools/aurac/aurac`).
- **Live preview:** “AURA: Open Preview”, `Ctrl+K V`, the preview icon or status bar starts `tools/aura-view`. The preview follows the cursor, displays unsaved changes and diagnostics, and supports clicks, signals, animation Play/Pause, components, `preview` blocks, states, `bool` properties and zoom. The native viewer uses `BasicHost`; device, language and accessibility options require a custom host. Build it with `cmake --build build/dev --target aura-view`. See [Preview](preview.md) for direct configuration.
- **Colors:** Swatch and picker for `#rrggbb`/`#aarrggbb`, and a swatch and hover showing the value of `theme.<color>` (from the running preview).
- **Go to Definition and Rename:** Components, records, dialogs, screens, IDs, properties, states, and signals (details in `docs/aura-view.md`).
- **Icons:** AURA logo as the extension icon, as the `.aura` file icon (a separate version for dark themes, visible when the file icon theme permits language icons), and in the preview tab. Sources: `docs/images/aura-icon.svg` (icon) and `docs/images/aura-logo.svg` (logo with wordmark); `media/aura-file-dark.svg` is the icon with a light inner triangle.

## Installation

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

Packages the extension as a VSIX (without `vsce`) and installs it with `code --install-extension`. Then run “Developer: Reload Window” in VS Code.

Format on save (`settings.json`):

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

## Development

Tests and `generate.js` currently use external application fixtures. Set `AURA_APP=<fixture-root>` to a tree containing `app/ui` and `app/ui/aura-elements.json`; otherwise the parent of the AURA checkout is searched. Some tests expect specific files and anchors: an arbitrary UI tree is insufficient, and custom fixtures need matching test cases. `AURAC=<compiler>` overrides the compiler path.

- **Tests:** `node tools/aura-vscode/test/completion-test.js` checks completion at selected locations in copies of repository files (with a mock `vscode` module). `node tools/aura-vscode/test/format-test.js` formats copies of the `.aura` files from `app/ui` (in a temporary directory) and checks idempotence, that repository files remain unchanged, that scrambled copies are restored, and that `aurac` generates identical C++ code. `node tools/aura-vscode/test/navigation-test.js` checks Go to Definition and Rename. `node tools/aura-vscode/test/check-test.js` checks error checking (unsaved error, correction, delegation to the preview). Both look for the compiler at `build/dev/tools/aurac/aurac` (otherwise set `AURAC=...`).
- **Grammar and data:** `syntaxes/aura.tmLanguage.json` and `data/aura-data.json` (completion) are generated from `libs/aura-lang/include/aura/lang/schema.h` and the application's `aura-elements.json`: `node tools/aura-vscode/scripts/generate.js`. Regenerate and reinstall after schema changes. Theme values come from the running preview rather than from these files.