Refactor to more idiomatic Jaspr code (#12726)

This refactors some parts of the code to have more idiomatic Jaspr
components and reduce logic in `global_scripts.dart`.

- Implement a new `ComponentRef` system that in some capacity works
similar to server components (more limited and less elegant, but
functionally working). This is to unblock some improvements (some of
which are included in this PR) to the interactive components of the
website, as we can already start architecting towards server components
and write less manual dom logic.
- Change the `Dropdown` component to accept direct `toggle` and
`content` components, which simplifies it's implementation. Migrate
existing uses of `Dropdown`.
- Migrate the top TOC (renamed to `PageNav`) to use the `Dropdown`
component, as well as the new `ComponentRef`s. Split into separate
"site-subheader" and "pagenav" elements. Preparations for #12715
- Add a new `Tooltip` component and migrate the glossary tooltips to it
using the new `ComponentRef`s. Can be reused for #12600

---------

Co-authored-by: Parker Lougheed <[email protected]>

Author: schultek

site/lib/_sass/_site.scss

@@ -29,14 +29,14 @@
 @use 'components/misc';
 @use 'components/next-prev-nav';
 @use 'components/os-selector';
+@use 'components/pagenav';
 @use 'components/pill';
 @use 'components/quiz';
 @use 'components/sidebar';
 @use 'components/side-menu';
 @use 'components/site-switcher';
 @use 'components/tabs';
 @use 'components/theming';
-@use 'components/toc';
 @use 'components/tooltip';
 @use 'components/trailing';
 

site/lib/_sass/components/_header.scss

@@ -167,3 +167,26 @@ body.open_menu #menu-toggle span.material-symbols {
     }
   }
 }
+
+#site-subheader {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  align-items: center;
+
+  position: sticky;
+  top: var(--site-header-height);
+  z-index: var(--site-z-subheader);
+  height: var(--site-subheader-height);
+
+  font-family: var(--site-ui-fontFamily);
+  font-size: 0.875rem;
+
+  background-color: var(--site-base-bgColor);
+  border-bottom: 0.1rem solid var(--site-outline-variant);
+  box-shadow: 0 2px 4px rgba(0, 0, 0, .05);
+
+  @media (width < 240px), (width >= 1200px) {
+    display: none;
+  }
+}

site/lib/_sass/components/_toc.scss renamed to site/lib/_sass/components/_pagenav.scss

@@ -1,30 +1,6 @@
-#toc-top {
-  font-family: var(--site-ui-fontFamily);
-
-  display: none;
-  flex-direction: row;
-  flex-wrap: wrap;
-  justify-content: space-between;
-  align-content: center;
-  height: var(--site-subheader-height);
-
-  @media (min-width: 240px) {
-    display: flex;
-  }
-
-  @media (min-width: 1200px) {
-    display: none;
-  }
-
-  position: sticky;
-  top: var(--site-header-height);
-
-  background-color: var(--site-base-bgColor);
-  border-bottom: 0.1rem solid var(--site-outline-variant);
-  box-shadow: 0 2px 4px rgba(0, 0, 0, .05);
-
-  font-size: 0.875rem;
-  z-index: var(--site-z-subheader);
+#pagenav {
+  flex-grow: 1;
+  min-width: 0;
 
   >button.dropdown-button {
     display: flex;
@@ -58,25 +34,21 @@
   }
 
   .toc-current {
-    flex-wrap: nowrap;
-    white-space: nowrap;
-    overflow: hidden;
-
     display: none;
 
     @media (min-width: 320px) {
       display: flex;
     }
-  }
-
-  #current-header {
-    color: var(--site-base-fgColor-alt);
 
+    flex-wrap: nowrap;
+    white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
+
+    color: var(--site-base-fgColor-alt);
   }
 
-  .dropdown-content {
+  #pagenav-content {
     position: absolute;
     box-shadow: 0 2px 4px rgba(0, 0, 0, .05);
     border-bottom: 0.1rem solid var(--site-outline-variant);
@@ -106,7 +78,7 @@
       max-width: 24rem;
     }
 
-    >a {
+    a#return-to-top {
       margin: 0.4rem 0;
       padding: 0.1rem;
       font-size: 1rem;
@@ -134,7 +106,7 @@
       }
     }
 
-    >nav {
+    nav {
       padding: 0.6rem 0 0.8rem;
     }
   }

site/lib/_sass/components/_side-menu.scss

@@ -1,4 +1,4 @@
-.styled-toc-list {
+.toc-list {
   margin: 0;
   --toc-indent: 0;
 

site/lib/_sass/components/_tooltip.scss

@@ -1,7 +1,7 @@
 .tooltip-wrapper {
   position: relative;
 
-  a.tooltip-target {
+  .tooltip-target a {
     color: inherit;
     text-decoration: underline;
     text-decoration-style: dotted;
@@ -10,14 +10,13 @@
   .tooltip {
     visibility: hidden;
 
-    display: flex;
+    display: block;
     position: absolute;
     z-index: var(--site-z-floating);
     top: 100%;
     left: 50%;
     transform: translateX(-50%);
 
-    flex-flow: column nowrap;
     width: 16rem;
 
     background: var(--site-raised-bgColor);
@@ -26,20 +25,22 @@
     box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, .15);
     padding: 0.8rem;
 
-    font-size: 1rem;
+    font-size: 0.875rem;
     font-weight: normal;
     font-style: normal;
 
+    .tooltip-content {
+      display: flex;
+      flex-flow: column nowrap;
+      color: var(--site-secondary-textColor);
+    }
+
     .tooltip-header {
       font-size: 1.2rem;
       font-weight: 500;
       margin-bottom: 0.25rem;
     }
 
-    .tooltip-content {
-      font-size: 0.875rem;
-      color: var(--site-secondary-textColor);
-    }
   }
 
   // On non-touch devices, show tooltip on hover or focus.
@@ -53,7 +54,7 @@
     }
   }
 
-  // On touch devices, show tooltip on click (see global_scripts.dart).
+  // On touch devices, show tooltip on click.
   @media all and (pointer: coarse) {
     .tooltip.visible {
       visibility: visible;

site/lib/jaspr_options.dart

@@ -19,25 +19,29 @@ import 'package:docs_flutter_dev_site/src/components/common/client/on_this_page_
     as prefix5;
 import 'package:docs_flutter_dev_site/src/components/common/client/os_selector.dart'
     as prefix6;
-import 'package:docs_flutter_dev_site/src/components/dartpad/dartpad_injector.dart'
+import 'package:docs_flutter_dev_site/src/components/common/client/simple_tooltip.dart'
     as prefix7;
-import 'package:docs_flutter_dev_site/src/components/layout/menu_toggle.dart'
+import 'package:docs_flutter_dev_site/src/components/dartpad/dartpad_injector.dart'
     as prefix8;
-import 'package:docs_flutter_dev_site/src/components/layout/site_switcher.dart'
+import 'package:docs_flutter_dev_site/src/components/layout/client/pagenav.dart'
     as prefix9;
-import 'package:docs_flutter_dev_site/src/components/layout/theme_switcher.dart'
+import 'package:docs_flutter_dev_site/src/components/layout/menu_toggle.dart'
     as prefix10;
-import 'package:docs_flutter_dev_site/src/components/pages/archive_table.dart'
+import 'package:docs_flutter_dev_site/src/components/layout/site_switcher.dart'
     as prefix11;
-import 'package:docs_flutter_dev_site/src/components/pages/glossary_search_section.dart'
+import 'package:docs_flutter_dev_site/src/components/layout/theme_switcher.dart'
     as prefix12;
-import 'package:docs_flutter_dev_site/src/components/pages/learning_resource_filters.dart'
+import 'package:docs_flutter_dev_site/src/components/pages/archive_table.dart'
     as prefix13;
-import 'package:docs_flutter_dev_site/src/components/pages/learning_resource_filters_sidebar.dart'
+import 'package:docs_flutter_dev_site/src/components/pages/glossary_search_section.dart'
     as prefix14;
-import 'package:docs_flutter_dev_site/src/components/tutorial/client/quiz.dart'
+import 'package:docs_flutter_dev_site/src/components/pages/learning_resource_filters.dart'
     as prefix15;
-import 'package:jaspr_content/components/file_tree.dart' as prefix16;
+import 'package:docs_flutter_dev_site/src/components/pages/learning_resource_filters_sidebar.dart'
+    as prefix16;
+import 'package:docs_flutter_dev_site/src/components/tutorial/client/quiz.dart'
+    as prefix17;
+import 'package:jaspr_content/components/file_tree.dart' as prefix18;
 
 /// Default [JasprOptions] for use with your jaspr project.
 ///
@@ -88,49 +92,59 @@ JasprOptions get defaultJasprOptions => JasprOptions(
       'src/components/common/client/os_selector',
     ),
 
-    prefix7.DartPadInjector: ClientTarget<prefix7.DartPadInjector>(
+    prefix7.SimpleTooltip: ClientTarget<prefix7.SimpleTooltip>(
+      'src/components/common/client/simple_tooltip',
+      params: _prefix7SimpleTooltip,
+    ),
+
+    prefix8.DartPadInjector: ClientTarget<prefix8.DartPadInjector>(
       'src/components/dartpad/dartpad_injector',
-      params: _prefix7DartPadInjector,
+      params: _prefix8DartPadInjector,
+    ),
+
+    prefix9.PageNav: ClientTarget<prefix9.PageNav>(
+      'src/components/layout/client/pagenav',
+      params: _prefix9PageNav,
     ),
 
-    prefix8.MenuToggle: ClientTarget<prefix8.MenuToggle>(
+    prefix10.MenuToggle: ClientTarget<prefix10.MenuToggle>(
       'src/components/layout/menu_toggle',
     ),
 
-    prefix9.SiteSwitcher: ClientTarget<prefix9.SiteSwitcher>(
+    prefix11.SiteSwitcher: ClientTarget<prefix11.SiteSwitcher>(
       'src/components/layout/site_switcher',
     ),
 
-    prefix10.ThemeSwitcher: ClientTarget<prefix10.ThemeSwitcher>(
+    prefix12.ThemeSwitcher: ClientTarget<prefix12.ThemeSwitcher>(
       'src/components/layout/theme_switcher',
     ),
 
-    prefix11.ArchiveTable: ClientTarget<prefix11.ArchiveTable>(
+    prefix13.ArchiveTable: ClientTarget<prefix13.ArchiveTable>(
       'src/components/pages/archive_table',
-      params: _prefix11ArchiveTable,
+      params: _prefix13ArchiveTable,
     ),
 
-    prefix12.GlossarySearchSection:
-        ClientTarget<prefix12.GlossarySearchSection>(
+    prefix14.GlossarySearchSection:
+        ClientTarget<prefix14.GlossarySearchSection>(
           'src/components/pages/glossary_search_section',
         ),
 
-    prefix13.LearningResourceFilters:
-        ClientTarget<prefix13.LearningResourceFilters>(
+    prefix15.LearningResourceFilters:
+        ClientTarget<prefix15.LearningResourceFilters>(
           'src/components/pages/learning_resource_filters',
         ),
 
-    prefix14.LearningResourceFiltersSidebar:
-        ClientTarget<prefix14.LearningResourceFiltersSidebar>(
+    prefix16.LearningResourceFiltersSidebar:
+        ClientTarget<prefix16.LearningResourceFiltersSidebar>(
           'src/components/pages/learning_resource_filters_sidebar',
         ),
 
-    prefix15.InteractiveQuiz: ClientTarget<prefix15.InteractiveQuiz>(
+    prefix17.InteractiveQuiz: ClientTarget<prefix17.InteractiveQuiz>(
       'src/components/tutorial/client/quiz',
-      params: _prefix15InteractiveQuiz,
+      params: _prefix17InteractiveQuiz,
     ),
   },
-  styles: () => [...prefix16.FileTree.styles],
+  styles: () => [...prefix18.FileTree.styles],
 );
 
 Map<String, dynamic> _prefix2CopyButton(prefix2.CopyButton c) => {
@@ -145,17 +159,25 @@ Map<String, dynamic> _prefix3DownloadLatestButton(
 Map<String, dynamic> _prefix4FeedbackComponent(prefix4.FeedbackComponent c) => {
   'issueUrl': c.issueUrl,
 };
-Map<String, dynamic> _prefix7DartPadInjector(prefix7.DartPadInjector c) => {
+Map<String, dynamic> _prefix7SimpleTooltip(prefix7.SimpleTooltip c) => {
+  'target': c.target.toId(),
+  'content': c.content.toId(),
+};
+Map<String, dynamic> _prefix8DartPadInjector(prefix8.DartPadInjector c) => {
   'title': c.title,
   'theme': c.theme,
   'height': c.height,
   'runAutomatically': c.runAutomatically,
 };
-Map<String, dynamic> _prefix11ArchiveTable(prefix11.ArchiveTable c) => {
+Map<String, dynamic> _prefix9PageNav(prefix9.PageNav c) => {
+  'title': c.title,
+  'content': c.content.toId(),
+};
+Map<String, dynamic> _prefix13ArchiveTable(prefix13.ArchiveTable c) => {
   'os': c.os,
   'channel': c.channel,
 };
-Map<String, dynamic> _prefix15InteractiveQuiz(prefix15.InteractiveQuiz c) => {
+Map<String, dynamic> _prefix17InteractiveQuiz(prefix17.InteractiveQuiz c) => {
   'title': c.title,
   'questions': c.questions.map((i) => i.toJson()).toList(),
 };

site/lib/main.dart

@@ -21,6 +21,7 @@ import 'src/components/pages/expansion_list.dart';
 import 'src/components/pages/learning_resource_index.dart';
 import 'src/components/tutorial/progress_ring.dart';
 import 'src/components/tutorial/quiz.dart';
+import 'src/components/util/component_ref.dart';
 import 'src/extensions/registry.dart';
 import 'src/layouts/catalog_page_layout.dart';
 import 'src/layouts/doc_layout.dart';
@@ -36,7 +37,7 @@ void main() {
   // Initializes the server environment with the generated default options.
   Jaspr.initializeApp(options: defaultJasprOptions);
 
-  runApp(_docsFlutterDevSite);
+  runApp(ComponentRefScope(child: _docsFlutterDevSite));
 }
 
 Component get _docsFlutterDevSite => ContentApp.custom(