diff --git a/docs/docs.json b/docs/docs.json index 0be5b475..a63c419a 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -262,6 +262,17 @@ ] } ] + }, + { + "tab": "Tools", + "groups": [ + { + "group": "Editor Extensions", + "pages": [ + "tools/vscode" + ] + } + ] } ] }, diff --git a/docs/tools/vscode.mdx b/docs/tools/vscode.mdx new file mode 100644 index 00000000..c45e2153 --- /dev/null +++ b/docs/tools/vscode.mdx @@ -0,0 +1,121 @@ +--- +title: "Use Stac in VS Code" +description: "Install and configure the Stac extension for VS Code. Get live preview, wrap quick-fixes, and snippets for Server-Driven UI — right inside your editor." +--- + +## Prerequisites + +- **Flutter SDK** with Dart `3.9.2+` +- A Flutter project using the [Stac](https://stac.dev) framework + +## Install the extension + +Click the link for your IDE to install directly: + +- [Install for VS Code](vscode:extension/StacDev.stac-vscode) +- [Install for Cursor](cursor:extension/StacDev.stac-vscode) +- [Install for Antigravity](antigravity:extension/StacDev.stac-vscode) + +Or in VS Code, press `Cmd+Shift+X` (Mac) or `Ctrl+Shift+X` (Windows/Linux) to open the Extensions view, search for "Stac", and click **Install**. + +## Get started + +1. **Open a Stac project** — open any Flutter project that uses the Stac framework. +2. **Open the Command Palette** — press `⌘⇧P` (Mac) or `Ctrl+Shift+P` (Windows / Linux) and type **"Stac"**. +3. **Launch a live preview** — run **`Stac: Open Preview`** to open a side-by-side preview of the active `@StacScreen`. + + + Stac Live Preview + + +## Use live preview + +The preview panel renders your `@StacScreen` in real time and updates automatically on save. + +- **Device toggles** — switch between Android, iOS, and Web viewports. +- **Theme picker** — preview with any `@StacThemeRef` theme defined in your project. +- **Auto-refresh** — every time you save, the preview re-renders. Disable this with the `stacVscode.preview.autoRefreshOnSave` setting. + +### Preview commands + +| Command | Description | +| --- | --- | +| `Stac: Open Preview` | Open the live preview panel for the active screen | +| `Stac: Select Preview Screen` | Switch to a different screen in the current file | +| `Stac: Stop Preview` | Stop the preview host process | + +## Use wrap quick-fixes + +Place your cursor on any Stac widget expression and press `⌘.` (Mac) or `Ctrl+.` (Windows / Linux) to wrap it with a preset widget: + +`StacContainer` · `StacPadding` · `StacCenter` · `StacAlign` · `StacSizedBox` · `StacExpanded` + +Select **Wrap with Stac widget…** to wrap with any custom Stac widget class in your project. + + + You can customise which preset wrappers appear in the quick-fix menu with the `stacVscode.wrapPresets` setting, or disable wrap actions entirely with `stacVscode.enableWrapQuickFix`. + + +## Use snippets + +In files containing `@StacScreen`, `@StacThemeRef`, or `package:stac_core`, the following snippets are available: + +| Prefix | What it creates | +| --- | --- | +| `stac screen` | A new screen template | +| `stac theme` | A new theme template | + +Snippets can be toggled with the `stacVscode.enableSnippets` setting. + +## Commands and shortcuts + +Open the Command Palette (`⌘⇧P` / `Ctrl+Shift+P`) and type **"Stac"** to see all available commands: + +| Command | Description | +| --- | --- | +| `Stac: Open Preview` | Open the live preview panel | +| `Stac: Select Preview Screen` | Switch screen in the current file | +| `Stac: Stop Preview` | Stop the preview host | +| `Stac: Regenerate Catalog` | Rebuild the widget catalog from `stac_core` | + +## Configure settings + +Open VS Code settings (`⌘,` / `Ctrl+,`) and search **"Stac"** to customise the extension. + +### Extension settings + +| Setting | Default | Description | +| --- | --- | --- | +| `stacVscode.enableWrapQuickFix` | `true` | Enable wrap quick-fix actions | +| `stacVscode.wrapPresets` | All presets | Preset wrappers shown in the quick-fix menu | +| `stacVscode.enableSnippets` | `true` | Enable `stac screen` / `stac theme` snippets | +| `stacVscode.preview.enable` | `true` | Enable preview commands | +| `stacVscode.preview.autoRefreshOnSave` | `true` | Refresh the preview on save | +| `stacVscode.preview.jsonStrategy` | `runnerThenBuild` | JSON generation strategy | +| `stacVscode.preview.hostPort` | `47841` | Local preview host port | +| `stacVscode.preview.startupTimeoutMs` | `120000` | Host startup timeout (ms) | + +## Troubleshooting + +### Preview won't start + +1. Open **Output → Stac Preview** for detailed logs. +2. Ensure your project builds successfully with `flutter run`. +3. Confirm the active file contains a `@StacScreen` annotation. +4. Try restarting the preview host by running **`Stac: Stop Preview`**, then **`Stac: Open Preview`**. + +### Extension won't install + +- Ensure you have a compatible version of VS Code (1.80.0 or later). +- Check that VS Code has permission to install extensions. +- Try installing directly from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=StacDev.stac-vscode). + +## Uninstall the extension + +1. Open the Extensions view (`⇧⌘X` / `Ctrl+Shift+X`). +2. Search for **"Stac"**. +3. Click **Uninstall**. + + + Found a bug or have a feature request? Open an issue on GitHub. + diff --git a/tools/stac-vscode/CHANGELOG.md b/tools/stac-vscode/CHANGELOG.md index 79ecc98c..8fa7ec9d 100644 --- a/tools/stac-vscode/CHANGELOG.md +++ b/tools/stac-vscode/CHANGELOG.md @@ -2,6 +2,10 @@ All notable changes to the "stac-vscode" extension will be documented in this file. +## [0.2.0] + +- Bug fixes & improvements + ## [0.1.0] ### Live Preview diff --git a/tools/stac-vscode/README.md b/tools/stac-vscode/README.md index 31b9837c..1869cad4 100644 --- a/tools/stac-vscode/README.md +++ b/tools/stac-vscode/README.md @@ -7,7 +7,8 @@ Build and preview Server-Driven UI screens with the **Stac** framework — direc ### 🔴 Live Preview Open a side-by-side preview of any `@StacScreen` — updates on save, supports theme selection, and renders with Android/iOS/Web platform simulation. -![Stac Live Preview](media/stac_preview.png) +![Stac Live Preview](https://raw.githubusercontent.com/StacDev/stac/dev/tools/stac-vscode/media/stac_preview.png) + - **`Stac: Open Preview`** — launch the preview panel for the active screen - **Device toggles** — switch between Android, iOS, and Web viewports diff --git a/tools/stac-vscode/package.json b/tools/stac-vscode/package.json index 6a5d6555..70ccdefc 100644 --- a/tools/stac-vscode/package.json +++ b/tools/stac-vscode/package.json @@ -2,7 +2,7 @@ "name": "stac-vscode", "displayName": "Stac", "description": "Build Server-Driven UI with Stac — live preview, wrap quick-fixes, and snippets for Flutter.", - "version": "0.1.0", + "version": "0.2.0", "publisher": "StacDev", "license": "MIT", "icon": "media/icon.png", @@ -207,4 +207,4 @@ "dependencies": { "js-yaml": "^4.1.1" } -} +} \ No newline at end of file