Add fallback text for sidebar failing to load (#3643)

* Add fallback text for sidebar failing to load

* Update for specific troubleshoot fragment

Author: parlough

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 8.0.6-wip
+
+* Add troubleshooting information when the sidebars failed to load.
+
 ## 8.0.5
 
 * Require `analyzer: ^6.4.1`.

dartdoc_options.yaml

@@ -1,4 +1,4 @@
 dartdoc:
   linkToSource:
     root: '.'
-    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v8.0.5/%f%#L%l%'
+    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v8.0.6-wip/%f%#L%l%'

lib/resources/docs.dart.js

@@ -1 +1 @@
-const packageVersion = '8.0.5';
+const packageVersion = '8.0.6-wip';

lib/resources/docs.dart.js.map

@@ -1,5 +1,5 @@
 name: dartdoc
-version: 8.0.5
+version: 8.0.6-wip
 description: A non-interactive HTML documentation generator for Dart source code.
 repository: https://github.com/dart-lang/dartdoc
 
@@ -25,7 +25,6 @@ dependencies:
 dev_dependencies:
   async: ^2.11.0
   dart_style: ^2.3.4
-  js: ^0.7.0
   lints: ^3.0.0
   matcher: ^0.12.15
   test: ^1.24.2

lib/src/version.dart

@@ -8,56 +8,72 @@ import 'highlight.dart' as highlight;
 import 'search.dart' as search;
 import 'sidenav.dart' as sidenav;
 import 'theme.dart' as theme;
+import 'web_interop.dart';
 
 void main() {
-  highlight.init();
   initializeSidebars();
-  sidenav.init();
   search.init();
+  sidenav.init();
+  highlight.init();
   theme.init();
 }
 
 void initializeSidebars() {
-  final body = document.querySelector('body');
+  final body = document.body;
   if (body == null) {
     return;
   }
-  final dataUsingBaseHref = body.dataset['using-base-href'];
+  final dataUsingBaseHref = body.getAttribute('data-using-base-href');
   if (dataUsingBaseHref == null) {
     // This should never happen.
     return;
   }
-  var baseHref = '';
+  final String baseHref;
   if (dataUsingBaseHref != 'true') {
-    final dataBaseHref = body.dataset['base-href'];
+    final dataBaseHref = body.getAttribute('data-base-href');
     if (dataBaseHref == null) {
       return;
     }
     baseHref = dataBaseHref;
+  } else {
+    baseHref = '';
   }
-  final mainContent = document.querySelector('#dartdoc-main-content');
+
+  final mainContent = document.getElementById('dartdoc-main-content');
   if (mainContent == null) {
     return;
   }
-  final aboveSidebarPath = mainContent.dataset['above-sidebar'];
-  final leftSidebar = document.querySelector('#dartdoc-sidebar-left-content');
   final sanitizer = _SidebarNodeTreeSanitizer(baseHref);
-  if (aboveSidebarPath != null &&
-      aboveSidebarPath.isNotEmpty &&
-      leftSidebar != null) {
-    HttpRequest.getString('$baseHref$aboveSidebarPath').then((content) {
-      leftSidebar.setInnerHtml(content, treeSanitizer: sanitizer);
-    });
-  }
-  final belowSidebarPath = mainContent.dataset['below-sidebar'];
-  final rightSidebar = document.querySelector('#dartdoc-sidebar-right');
-  if (belowSidebarPath != null &&
-      belowSidebarPath.isNotEmpty &&
-      rightSidebar != null) {
-    HttpRequest.getString('$baseHref$belowSidebarPath').then((content) {
-      rightSidebar.setInnerHtml(content, treeSanitizer: sanitizer);
+
+  void loadSidebar(String? sidebarPath, Element? sidebarElement) {
+    if (sidebarPath == null || sidebarPath.isEmpty || sidebarElement == null) {
+      return;
+    }
+
+    window.fetch('$baseHref$sidebarPath').then((response) async {
+      final fetchResponse = response as FetchResponse;
+      if (response.status != 200) {
+        final errorAnchor = (document.createElement('a') as AnchorElement)
+          ..href = 'https://dart.dev/tools/dart-doc#troubleshoot'
+          ..text = 'Failed to load sidebar. '
+              'Visit dart.dev for help troubleshooting.';
+        sidebarElement.append(errorAnchor);
+        return;
+      }
+
+      final content = await fetchResponse.text;
+
+      sidebarElement.setInnerHtml(content, treeSanitizer: sanitizer);
     });
   }
+
+  final aboveSidebarPath = mainContent.getAttribute('data-above-sidebar');
+  final leftSidebar = document.getElementById('dartdoc-sidebar-left-content');
+  loadSidebar(aboveSidebarPath, leftSidebar);
+
+  final belowSidebarPath = mainContent.getAttribute('data-below-sidebar');
+  final rightSidebar = document.getElementById('dartdoc-sidebar-right');
+  loadSidebar(belowSidebarPath, rightSidebar);
 }
 
 /// A permissive sanitizer that allows external links (e.g. to api.dart.dev) and

pubspec.yaml

@@ -2,15 +2,15 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import 'package:js/js.dart';
+import 'dart:js_interop';
 
 void init() {
   highlight?.highlightAll();
 }
 
 @JS()
 @staticInterop
-class HighlightJs {}
+final class HighlightJs {}
 
 extension HighlightJsExtension on HighlightJs {
   external void highlightAll();

web/docs.dart

@@ -36,14 +36,13 @@ void init() {
   }
 
   window.fetch('${_htmlBase}index.json').then((response) async {
-    response = response as FetchResponse;
-    var code = response.status;
-    if (code == 404) {
+    final fetchResponse = response as FetchResponse;
+    if (fetchResponse.status != 200) {
       disableSearch();
       return;
     }
 
-    var text = await response.text;
+    final text = await fetchResponse.text;
     final index = Index.fromJson(text);
 
     // Navigate to the first result from the 'search' query parameter

web/highlight.dart

@@ -1 +1 @@
-8C67B39F09940FC20D8C13F6BBE0B1EE
+157D433EE554B00A24CAF73333958091

web/search.dart

@@ -2,22 +2,17 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import 'dart:js_util' as js_util;
-
-import 'package:js/js.dart';
+import 'dart:js_interop';
 
 @JS('Response')
 @staticInterop
-class FetchResponse {}
+final class FetchResponse {}
 
 extension FetchResponseExtension on FetchResponse {
   external int get status;
 
   @JS('text')
-  external Promise _text();
-  Future<String> get text => js_util.promiseToFuture(_text());
+  external JSPromise _text();
+  Future<String> get text async =>
+      ((await _text().toDart) as JSString).toString();
 }
-
-@JS()
-@staticInterop
-class Promise {}