Saving inital Docs POC

docs/ux-best-practices.md

@@ -0,0 +1,131 @@
+# UX Best Practices for Volar-based Language Servers
+
+> [Docs Index](README.md) • [Repo README](../README.md) • [Telemetry](telemetry-and-observability.md) • [Error Handling](error-handling-and-resilience.md)
+
+A language server lives inside the editor experience; thoughtful UX keeps users confident and productive. This guide focuses on user-facing behaviors—status messages, progress indicators, error notifications, settings UX, and documentation—for Volar integrations.
+
+## Goals
+
+1. **Transparency** – users know what the server is doing (diagnostics running, schema fetching, errors).
+2. **Actionable feedback** – every warning/error tells the user how to resolve it.
+3. **Control** – users can adjust settings, restart the server, or disable features when necessary.
+
+## Status & Progress Indicators
+
+### Initial Load / Heavy Tasks
+
+- Use work-done progress for long-running operations (>500ms).
+
+```ts
+async function withProgress(title: string, task: () => Promise<void>) {
+  const progress = await connection.window.createWorkDoneProgress();
+  progress.begin(title);
+  try {
+    await task();
+  } finally {
+    progress.done();
+  }
+}
+```
+
+Examples:
+
+- “Volar (JSON/YAML): Indexing workspace…”
+- “Fetching schemas…”
+
+### Idle Status
+
+- Provide a summary command (VS Code command or Neovim RPC) that returns current workspace stats: number of open documents, diagnostics pending, schema cache status.
+- Show a status bar entry with quick access to commands (e.g., “Volar: Ready • Diagnostics: 12”).
+
+## Notifications
+
+Use the right severity for notifications:
+
+| Scenario | API | Message |
+| --- | --- | --- |
+| Non-blocking info (feature enabled) | `showInformationMessage` | “Volar Take Over Mode is now active.” |
+| Recoverable issue | `showWarningMessage` | “Failed to fetch schema. Using cached version.” |
+| Action required | `showErrorMessage` | “Invalid configuration: volarJsonYaml.schemas must be an array.” |
+
+Tips:
+
+- Provide action buttons: `showWarningMessage(msg, 'Retry', 'Open Settings')`.
+- Limit frequency—use throttling so the same warning doesn’t appear repeatedly.
+
+## Settings UX
+
+### Documentation
+
+- Publish a markdown file (e.g., `docs/configuration-and-projects.md`) describing every setting with default values and examples.
+- If shipping a VS Code extension, include configuration defaults in `package.json` with `markdownDescription`.
+
+### Validation & Feedback
+
+- When settings are invalid, log the error and notify users with actionable instructions (“Set `volarJsonYaml.schemas` to an array of objects. See docs URL.”).
+- Provide commands or links that open the relevant settings file (VS Code: `workbench.action.openSettingsJson`).
+
+### Profiles / Presets
+
+- Offer easy ways to switch between configurations (commands like “Volar: Use Strict Profile”).
+- Document the effect of each profile (diagnostic severity, Take Over Mode, etc.).
+
+## Command Palette & Shortcuts
+
+Provide commands for common tasks:
+
+- “Volar: Restart Language Server”
+- “Volar: Clear Schema Cache”
+- “Volar: Show Server Logs”
+- “Volar: Toggle Take Over Mode”
+
+In Neovim/Sublime, expose equivalents via user commands (`:VolarRestart`, etc.).
+
+## Error Messaging
+
+| Bad | Good |
+| --- | --- |
+| “Schema fetch failed” | “Schema fetch failed (404). Using cached schema from 2024-05-12. Configure schemas in volarJsonYaml.schemas.” |
+| “Config invalid” | “Invalid volarJsonYaml.diagnostics.severity: expected string 'error' | 'warn' | 'info'. Reverted to 'warn'. See docs/…” |
+
+Guidelines:
+
+- Include cause, fallback action, and next steps.
+- Link to docs or open configuration automatically when possible.
+
+## Editor Integration Details
+
+### VS Code
+
+- Status bar entry (`window.createStatusBarItem`) with commands.
+- Register commands for restart/refresh in `package.json`.
+- Respect VS Code’s log level (use `connection.console` so logs appear in “Output ▸ Volar”).
+
+### Neovim
+
+- Provide Lua callbacks to show server status, toggle settings, or display logs.
+- Write to a log file (`~/.cache/volar/log.txt`) for easy sharing.
+
+### CLI
+
+- Print progress messages (e.g., “Analyzing 120 files…”) with a spinner.
+- Exit with non-zero status when diagnostics contain errors; print summary at the end.
+
+## Documentation & Support
+
+- Maintain a “Known Issues” section (Take Over Mode pitfalls, incompatible extensions).
+- Provide reproduction steps for common fixes (clearing Vite cache, installing TS 5.x).
+- Encourage users to attach logs + configuration when filing issues; document how to retrieve them.
+
+## UX Checklist
+
+- [ ] Progress indicators for long tasks.
+- [ ] Status bar/command to show server status.
+- [ ] Clear, actionable notifications for errors/warnings.
+- [ ] Settings documented with defaults and examples.
+- [ ] Commands for restart, cache clearing, log viewing.
+- [ ] Error messages include cause + next steps.
+- [ ] Logs accessible via editor output or file.
+- [ ] CLI/Neovim equivalents for key UX features.
+
+Thoughtful UX turns a powerful language server into a delightful developer experience. Communicate clearly, surface actionable options, and give users control over how Volar behaves within their editors.