Migrate page feedback component to Jaspr (#6874)

Contributes to #6853

Author: parlough

site/lib/_sass/components/_trailing.scss

@@ -30,39 +30,13 @@
     }
   }
 
-  .initial-feedback {
-    .feedback-buttons {
-      display: flex;
-      flex-direction: row;
-      gap: 0.5rem;
-
-      span.material-symbols {
-        font-size: 20px;
-      }
-    }
-  }
-
-  .good-feedback, .bad-feedback {
-    display: none;
-  }
-
-  &.feedback-up {
-    .initial-feedback {
-      display: none;
-    }
-
-    .good-feedback {
-      display: flex;
-    }
-  }
-
-  &.feedback-down {
-    .initial-feedback {
-      display: none;
-    }
+  .feedback-buttons {
+    display: flex;
+    flex-direction: row;
+    gap: 0.5rem;
 
-    .bad-feedback {
-      display: flex;
+    span.material-symbols {
+      font-size: 20px;
     }
   }
 }

site/lib/jaspr_options.dart

@@ -8,6 +8,7 @@ import 'package:jaspr/jaspr.dart';
 import 'package:dart_dev_site/src/archive/archive_table.dart' as prefix0;
 import 'package:dart_dev_site/src/components/cookie_notice.dart' as prefix1;
 import 'package:dart_dev_site/src/components/copy_button.dart' as prefix2;
+import 'package:dart_dev_site/src/components/feedback.dart' as prefix3;
 
 /// Default [JasprOptions] for use with your jaspr project.
 ///
@@ -40,6 +41,11 @@ JasprOptions get defaultJasprOptions => JasprOptions(
       'src/components/copy_button',
       params: _prefix2CopyButton,
     ),
+
+    prefix3.FeedbackComponent: ClientTarget<prefix3.FeedbackComponent>(
+      'src/components/feedback',
+      params: _prefix3FeedbackComponent,
+    ),
   },
   styles: () => [],
 );
@@ -53,3 +59,6 @@ Map<String, dynamic> _prefix2CopyButton(prefix2.CopyButton c) => {
   'classes': c.classes,
   'title': c.title,
 };
+Map<String, dynamic> _prefix3FeedbackComponent(prefix3.FeedbackComponent c) => {
+  'issueUrl': c.issueUrl,
+};

site/lib/src/analytics/analytics.dart

@@ -0,0 +1,21 @@
+// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
+// 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:meta/meta.dart';
+
+import 'analytics_server.dart'
+    if (dart.library.js_interop) 'analytics_web.dart';
+
+/// Used to report analytic events.
+final analytics = AnalyticsImplementation();
+
+/// Contains methods for reporting analytics events.
+abstract class Analytics {
+  @internal
+  void sendEvent(String eventName, Map<String, Object?> parameters);
+
+  void sendFeedback(bool helpful) {
+    sendEvent('feedback', {'feedback_type': helpful ? 'up' : 'down'});
+  }
+}

site/lib/src/analytics/analytics_server.dart

@@ -0,0 +1,18 @@
+// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
+// 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:meta/meta.dart';
+
+import 'analytics.dart';
+
+/// Server implementation of [Analytics].
+///
+/// Don't use directly. Access through [analytics] instead.
+@internal
+final class AnalyticsImplementation extends Analytics {
+  @override
+  void sendEvent(String eventName, Map<String, Object?> parameters) {
+    // Ignore on the server.
+  }
+}

site/lib/src/analytics/analytics_web.dart

@@ -0,0 +1,28 @@
+// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
+// 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:meta/meta.dart';
+import 'package:universal_web/js_interop.dart';
+import 'package:universal_web/web.dart' as web;
+
+import 'analytics.dart';
+
+/// Web implementation of [Analytics].
+///
+/// Don't use directly. Access through [analytics] instead.
+@internal
+final class AnalyticsImplementation extends Analytics {
+  @override
+  void sendEvent(String eventName, Map<String, Object?> parameters) {
+    final dataLayer = web.window['dataLayer'];
+    if (dataLayer.isA<JSArray>()) {
+      (dataLayer as JSArray).toDart.add(
+        {
+          'event': eventName,
+          ...parameters,
+        }.jsify(),
+      );
+    }
+  }
+}

site/lib/src/components/feedback.dart

@@ -0,0 +1,90 @@
+// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
+// 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:jaspr/jaspr.dart';
+
+import '../analytics/analytics.dart';
+import 'button.dart';
+
+/// Provides the user options to provide feedback on the specified page.
+@client
+final class FeedbackComponent extends StatefulComponent {
+  const FeedbackComponent({required this.issueUrl});
+
+  final String issueUrl;
+
+  @override
+  State<FeedbackComponent> createState() => _FeedbackComponentState();
+}
+
+final class _FeedbackComponentState extends State<FeedbackComponent> {
+  _FeedbackState feedback = _FeedbackState.none;
+
+  void _provideFeedback({required bool helpful}) {
+    if (!kIsWeb) return;
+
+    setState(
+      () => feedback = helpful
+          ? _FeedbackState.helpful
+          : _FeedbackState.unhelpful,
+    );
+    analytics.sendFeedback(helpful);
+  }
+
+  @override
+  Component build(BuildContext context) {
+    return div(id: 'page-feedback', [
+      div(classes: 'feedback', [
+        div([Component.text(feedback.introduction)]),
+        ...switch (feedback) {
+          _FeedbackState.none => [
+            div(classes: 'feedback-buttons', [
+              Button(
+                icon: 'thumb_up',
+                title: 'Yes, this page was helpful.',
+                onClick: () => _provideFeedback(helpful: true),
+              ),
+              Button(
+                icon: 'thumb_down',
+                title: 'No, this page was not helpful or had an issue',
+                onClick: () => _provideFeedback(helpful: false),
+              ),
+            ]),
+          ],
+          _FeedbackState.helpful => [
+            Button(
+              content: 'Provide details',
+              icon: 'feedback',
+              title: 'Provide detailed feedback.',
+              href: component.issueUrl,
+              attributes: {'target': '_blank', 'rel': 'noopener'},
+            ),
+          ],
+          _FeedbackState.unhelpful => [
+            Button(
+              content: 'Provide details',
+              icon: 'bug_report',
+              title: 'Provide feedback or report an issue.',
+              href: component.issueUrl,
+              attributes: {'target': '_blank', 'rel': 'noopener'},
+            ),
+          ],
+        },
+      ]),
+    ]);
+  }
+}
+
+enum _FeedbackState {
+  none('Was this page\'s content helpful?'),
+  helpful('Thank you for your feedback!'),
+  unhelpful(
+    'Thank you for your feedback! '
+    'Please let us know what we can do to improve.',
+  );
+
+  const _FeedbackState(this.introduction);
+
+  final String introduction;
+}

site/lib/src/components/trailing_content.dart

@@ -5,6 +5,8 @@
 import 'package:jaspr/jaspr.dart';
 import 'package:jaspr_content/jaspr_content.dart';
 
+import 'feedback.dart';
+
 /// The trailing content of a content documentation page, such as
 /// its last updated information, report an issue links, and similar.
 class TrailingContent extends StatelessComponent {
@@ -50,90 +52,7 @@ class TrailingContent extends StatelessComponent {
       id: 'trailing-content',
       attributes: {'data-nosnippet': 'true'},
       [
-        div(id: 'page-feedback', [
-          div(classes: 'feedback initial-feedback', [
-            div([text('Was this page\'s content helpful?')]),
-            div(classes: 'feedback-buttons', [
-              button(
-                id: 'feedback-up-button',
-                classes: 'icon-button',
-                attributes: {
-                  'aria-label': 'Yes, this page was helpful',
-                  'title': 'Helpful',
-                },
-                [
-                  span(
-                    classes: 'material-symbols',
-                    attributes: {'aria-hidden': 'true'},
-                    [text('thumb_up')],
-                  ),
-                ],
-              ),
-              button(
-                id: 'feedback-down-button',
-                classes: 'icon-button',
-                attributes: {
-                  'aria-label': 'No, this page was not helpful or had an issue',
-                  'title': 'Not helpful or had issue',
-                },
-                [
-                  span(
-                    classes: 'material-symbols',
-                    attributes: {'aria-hidden': 'true'},
-                    [text('thumb_down')],
-                  ),
-                ],
-              ),
-            ]),
-          ]),
-
-          div(classes: 'feedback good-feedback', [
-            div([text('Thank you for your feedback!')]),
-            a(
-              href: issueUrl,
-              classes: 'text-button',
-              attributes: {
-                'aria-label': 'Provide feedback',
-                'target': '_blank',
-                'rel': 'noopener',
-              },
-              [
-                span(
-                  classes: 'material-symbols',
-                  attributes: {'aria-hidden': 'true'},
-                  [text('feedback')],
-                ),
-                span([text('Provide details')]),
-              ],
-            ),
-          ]),
-
-          div(classes: 'feedback bad-feedback', [
-            div([
-              text(
-                'Thank you for your feedback!'
-                'Please let us know what we can do to improve.',
-              ),
-            ]),
-            a(
-              href: issueUrl,
-              classes: 'text-button',
-              attributes: {
-                'aria-label': 'Provide feedback or report an issue',
-                'target': '_blank',
-                'rel': 'noopener',
-              },
-              [
-                span(
-                  classes: 'material-symbols',
-                  attributes: {'aria-hidden': 'true'},
-                  [text('bug_report')],
-                ),
-                span([text('Provide details')]),
-              ],
-            ),
-          ]),
-        ]),
+        FeedbackComponent(issueUrl: issueUrl),
 
         p(id: 'page-github-links', [
           span([

site/web/assets/js/main.js

@@ -378,28 +378,6 @@ function setupExpandableCards() {
   });
 }
 
-function setupFeedback() {
-  const feedbackContainer =
-      document.getElementById('page-feedback');
-  if (!feedbackContainer) return;
-
-  const feedbackUpButton = feedbackContainer.querySelector('#feedback-up-button');
-  const feedbackDownButton = feedbackContainer.querySelector('#feedback-down-button');
-  if (!feedbackUpButton || !feedbackDownButton) return;
-
-  feedbackUpButton.addEventListener('click', (_) => {
-    window.dataLayer?.push({'event': 'inline_feedback', 'feedback_type': 'up'});
-
-    feedbackContainer.classList.add('feedback-up');
-  }, { once: true });
-
-  feedbackDownButton.addEventListener('click', (_) => {
-    window.dataLayer?.push({'event': 'inline_feedback', 'feedback_type': 'down'});
-
-    feedbackContainer.classList.add('feedback-down');
-  }, { once: true });
-}
-
 function _setupSite() {
   setupTheme();
   setupSidenav();
@@ -452,7 +430,6 @@ function _setupSite() {
 
   setupTableOfContents();
   setupExpandableCards();
-  setupFeedback();
 }
 
 // Run setup if DOM is loaded, otherwise do it after it has loaded.