Display error messages in the Documentation Live Preview Editor (#1302)

Author: matthewbastien

.vscodeignore

@@ -8,4 +8,7 @@
 !dist/**
 !images/**
 !snippets/**
-!assets/icon-font.woff
+!assets/icons/**
+!assets/documentation-webview/**
+!assets/swift-docc-render/**
+!node_modules/@vscode/codicons/**

package-lock.json

@@ -1420,6 +1420,7 @@
     "typescript": "^5.7.2"
   },
   "dependencies": {
+    "@vscode/codicons": "^0.0.36",
     "lcov-parse": "^1.0.0",
     "plist": "^3.1.0",
     "vscode-languageclient": "^9.0.1",

package.json

@@ -2,7 +2,7 @@
 //
 // This source file is part of the VS Code Swift open source project
 //
-// Copyright (c) 2024 the VS Code Swift project authors
+// Copyright (c) 2024-2025 the VS Code Swift project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -40,6 +40,11 @@ export class DocumentationPreviewEditor implements vscode.Disposable {
             {
                 enableScripts: true,
                 localResourceRoots: [
+                    vscode.Uri.file(
+                        extension.asAbsolutePath(
+                            path.join("node_modules", "@vscode/codicons", "dist")
+                        )
+                    ),
                     vscode.Uri.file(
                         extension.asAbsolutePath(path.join("assets", "documentation-webview"))
                     ),
@@ -72,8 +77,16 @@ export class DocumentationPreviewEditor implements vscode.Disposable {
             path.join(swiftDoccRenderPath, "index.html"),
             "utf-8"
         );
+        const codiconsUri = webviewPanel.webview.asWebviewUri(
+            vscode.Uri.file(
+                extension.asAbsolutePath(
+                    path.join("node_modules", "@vscode/codicons", "dist", "codicon.css")
+                )
+            )
+        );
         doccRenderHTML = doccRenderHTML
             .replaceAll("{{BASE_PATH}}", webviewBaseURI.toString())
+            .replace("</head>", `<link href="${codiconsUri}" rel="stylesheet" /></head>`)
             .replace("</body>", `<script src="${scriptURI.toString()}"></script></body>`);
         webviewPanel.webview.html = doccRenderHTML;
         return new DocumentationPreviewEditor(context, webviewPanel);

src/documentation/DocumentationPreviewEditor.ts

@@ -0,0 +1,70 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the VS Code Swift open source project
+//
+// Copyright (c) 2025 the VS Code Swift project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of VS Code Swift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+export class ErrorMessage {
+    private readonly containerElement: HTMLDivElement;
+    private readonly iconElement: HTMLSpanElement;
+    private readonly messageElement: HTMLSpanElement;
+
+    constructor() {
+        this.containerElement = createContainer();
+        this.iconElement = createIcon();
+        this.messageElement = createMessage();
+        this.containerElement.appendChild(this.iconElement);
+        this.containerElement.appendChild(this.messageElement);
+        window.document.body.appendChild(this.containerElement);
+    }
+
+    show(message: string) {
+        this.messageElement.textContent = message;
+        this.containerElement.style.display = "flex";
+    }
+
+    hide() {
+        this.containerElement.style.display = "none";
+    }
+}
+
+function createContainer(): HTMLDivElement {
+    const containerElement = document.createElement("div");
+    containerElement.style.backgroundColor = "var(--vscode-editor-background)";
+    containerElement.style.color = "var(--vscode-foreground)";
+    containerElement.style.fontFamily = "var(--vscode-font-family)";
+    containerElement.style.fontWeight = "var(--vscode-font-weight)";
+    containerElement.style.width = "100%";
+    containerElement.style.height = "100%";
+    containerElement.style.display = "none";
+    containerElement.style.gap = "10px";
+    containerElement.style.flexDirection = "column";
+    containerElement.style.alignItems = "center";
+    containerElement.style.justifyContent = "center";
+    containerElement.style.position = "absolute";
+    containerElement.style.top = "0";
+    containerElement.style.left = "0";
+    return containerElement;
+}
+
+function createIcon(): HTMLSpanElement {
+    const iconElement = document.createElement("span");
+    iconElement.className = "codicon codicon-error";
+    iconElement.style.color = "var(--vscode-editorError-foreground)";
+    iconElement.style.fontSize = "48px";
+    return iconElement;
+}
+
+function createMessage(): HTMLSpanElement {
+    const messageElement = document.createElement("span");
+    messageElement.style.fontSize = "14px";
+    return messageElement;
+}

src/documentation/webview/ErrorMessage.ts

@@ -2,7 +2,7 @@
 //
 // This source file is part of the VS Code Swift open source project
 //
-// Copyright (c) 2024 the VS Code Swift project authors
+// Copyright (c) 2024-2025 the VS Code Swift project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -14,13 +14,15 @@
 
 import { RenderNode, WebviewContent, WebviewMessage } from "./WebviewMessage";
 import { createCommunicationBridge } from "./CommunicationBridge";
+import { ErrorMessage } from "./ErrorMessage";
 
 createCommunicationBridge().then(async bridge => {
     const vscode = acquireVsCodeApi();
     let activeDocumentationPath: string | undefined;
     let contentToApplyOnRender: RenderNode | undefined;
 
-    window.document.getElementById("app");
+    // An HTML element that displays an error message to the user
+    const errorMessage = new ErrorMessage();
 
     // Handle messages coming from swift-docc-render
     bridge.onDidReceiveMessage(message => {
@@ -53,6 +55,7 @@ createCommunicationBridge().then(async bridge => {
     });
     function handleUpdateContentMessage(content: WebviewContent) {
         if (content.type === "render-node") {
+            hideErrorMessage();
             const renderNode = content.renderNode;
             const documentationPath: string = (() => {
                 switch (renderNode.kind) {
@@ -76,10 +79,27 @@ createCommunicationBridge().then(async bridge => {
                 bridge.send({ type: "contentUpdate", data: renderNode });
             }
         } else {
-            // Show the error message
+            showErrorMessage(content.errorMessage);
+            vscode.postMessage({ type: "rendered" });
         }
     }
 
+    function showErrorMessage(message: string) {
+        const app = window.document.getElementById("app");
+        if (app) {
+            app.style.display = "none";
+        }
+        errorMessage.show(message);
+    }
+
+    function hideErrorMessage() {
+        const app = window.document.getElementById("app");
+        if (app) {
+            app.style.display = "block";
+        }
+        errorMessage.hide();
+    }
+
     // Notify vscode-swift that we're ready to receive messages
     vscode.postMessage({ type: "loaded" });
 });