Add optional page navigation to top toc dropdown (#12715)

This extends the top floating table-of-contents dropdown by an optional
page navigation list, for use inside FWE tutorials.

<img width="369" height="786" alt="Bildschirmfoto 2025-11-18 um 14 04
38"
src="https://github.com/user-attachments/assets/b85d3a07-cb01-4d39-9bce-f5f6f9828fca"
/>

---

Differences to the current toc:

- Instead of "On this page" shows the current page title
- When open, shows a list of pages (including chapters).
- The current page's toc is nested under the entry of the current page
(design & behavior stays the same)

To test this, I also created a new `TutorialLayout` that hides the
sidebar and forces the floating toc bar on all screen sizes. This should
be improved in the future.

---------

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

Author: schultek

site/lib/_sass/base/_base.scss

@@ -8,8 +8,10 @@ body {
   color: var(--site-base-fgColor);
 
   // The top TOC is not shown on narrow screens.
-  @media (min-width: 1200px) {
-    --site-subheader-height: 0rem;
+  &:not(:has(#site-subheader.show-always)) {
+    @media (min-width: 1200px) {
+      --site-subheader-height: 0rem;
+    }
   }
 
   // If the TOC is disabled, reduce the subheader height to

site/lib/_sass/components/_header.scss

@@ -7,8 +7,10 @@
   border-bottom: 0.1rem solid var(--site-outline-variant);
 
   @media (min-width: 1200px) {
-    box-shadow: 0 2px 4px rgba(0, 0, 0, .05);
-    border-bottom: none;
+    &:not(:has(~* #site-subheader.show-always)) {
+      box-shadow: 0 2px 4px rgba(0, 0, 0, .05);
+      border-bottom: none;
+    }
   }
 
   .navbar {
@@ -186,7 +188,9 @@ body.open_menu #menu-toggle span.material-symbols {
   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;
+  &:not(.show-always) {
+    @media (width < 240px), (width >= 1200px) {
+      display: none;
+    }
   }
 }

site/lib/_sass/components/_pagenav.scss

@@ -1,6 +1,7 @@
 #pagenav {
   flex-grow: 1;
   min-width: 0;
+  max-width: 100%;
 
   >button.dropdown-button {
     display: flex;
@@ -23,29 +24,56 @@
       color: var(--site-base-fgColor-alt);
       font-size: 20px;
     }
+
+    >.material-symbols:first-child {
+      margin-right: 0.25rem;
+    }
   }
 
-  .toc-intro {
+  .toc-breadcrumb {
+    flex-shrink: 2;
     white-space: nowrap;
+    overflow: hidden;
 
-    .material-symbols {
-      margin-right: 0.25rem;
+    &.toc-hide-medium {
+      @media (width < 576px) {
+        display: none;
+      }
     }
-  }
 
-  .toc-current {
-    display: none;
+    &.toc-hide-small {
+      @media (width < 420px) {
+        display: none;
+      }
+    }
 
-    @media (min-width: 320px) {
-      display: flex;
+    span:not(.material-symbols) {
+      overflow: hidden;
+      text-overflow: ellipsis;
     }
 
-    flex-wrap: nowrap;
+    .page-number {
+      flex-shrink: 0;
+      height: 1.3rem;
+      width: 1.3rem;
+
+      margin-right: 0.4rem;
+      background-color: var(--site-primary-color);
+      color: var(--site-onPrimary-color-lightest);
+    }
+  }
+
+  .toc-current {
+    flex-shrink: 1;
     white-space: nowrap;
     overflow: hidden;
-    text-overflow: ellipsis;
 
     color: var(--site-base-fgColor-alt);
+
+    span:last-child {
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
   }
 
   #pagenav-content {
@@ -64,7 +92,13 @@
     scrollbar-width: thin;
     overscroll-behavior: contain;
 
-    padding: 0.2rem 0.4rem;
+    padding: 0.5rem;
+
+    >div {
+      display: flex;
+      flex-direction: column;
+      gap: 0.25rem;
+    }
 
     @media (min-width: 420px) {
       border: none;
@@ -85,6 +119,7 @@
       text-decoration: none;
       display: flex;
       align-items: center;
+      gap: 4px;
       color: var(--site-base-fgColor-alt);
       font-weight: 500;
 
@@ -93,10 +128,6 @@
         user-select: none;
       }
 
-      span:last-child {
-        margin-left: 3px;
-      }
-
       &:hover {
         color: var(--site-link-fgColor);
       }
@@ -109,5 +140,58 @@
     nav {
       padding: 0.6rem 0 0.8rem;
     }
+
+    .page-link {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+
+      padding: 0;
+      font-weight: 400;
+      text-decoration: none;
+      color: var(--site-base-fgColor);
+
+      &:hover {
+        color: var(--site-link-fgColor);
+      }
+
+      &.active .page-number {
+        background-color: var(--site-primary-color);
+        color: var(--site-onPrimary-color-lightest);
+      }
+
+      &:not(.active):has(~.page-link.active) .page-number {
+        background-color: var(--site-onPrimary-color-light);
+        color: var(--site-primary-color);
+      }
+
+      ~nav {
+        padding: 0;
+      }
+    }
+
+    .page-divider {
+      padding: 0.25rem;
+      font-weight: 600;
+      color: var(--site-base-fgColor-alt);
+    }
+
+    .dropdown-divider:has(~.page-link) {
+      margin-top: 0.6rem;
+    }
+  }
+
+  .page-number {
+    width: 25px;
+    height: 25px;
+    border-radius: 50%;
+    background: var(--site-inset-borderColor);
+    color: var(--site-base-fgColor);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font-weight: 500;
+
+    transition: background-color 300ms ease, color 300ms ease;
   }
-}
+}

site/lib/_sass/components/_tooltip.scss

@@ -60,4 +60,4 @@
       visibility: visible;
     }
   }
-}
+}

site/lib/jaspr_options.dart

@@ -190,7 +190,9 @@ Map<String, dynamic> _prefix10DartPadInjector(prefix10.DartPadInjector c) => {
   'runAutomatically': c.runAutomatically,
 };
 Map<String, dynamic> _prefix11PageNav(prefix11.PageNav c) => {
-  'title': c.title,
+  'breadcrumbs': c.breadcrumbs,
+  'pageNumber': c.pageNumber,
+  'initialHeading': c.initialHeading,
   'content': c.content.toId(),
 };
 Map<String, dynamic> _prefix15ArchiveTable(prefix15.ArchiveTable c) => {

site/lib/main.dart

@@ -32,6 +32,7 @@ import 'src/components/util/component_ref.dart';
 import 'src/extensions/registry.dart';
 import 'src/layouts/doc_layout.dart';
 import 'src/layouts/toc_layout.dart';
+import 'src/layouts/tutorial_layout.dart';
 import 'src/loaders/data_processor.dart';
 import 'src/markdown/markdown_parser.dart';
 import 'src/pages/custom_pages.dart';
@@ -72,7 +73,11 @@ Component get _docsFlutterDevSite => ContentApp.custom(
     rawOutputPattern: _passThroughPattern,
     extensions: allNodeProcessingExtensions,
     components: _embeddableComponents,
-    layouts: const [DocLayout(), TocLayout()],
+    layouts: const [
+      DocLayout(),
+      TocLayout(),
+      TutorialLayout(),
+    ],
     theme: const ContentTheme.none(),
     secondaryOutputs: [
       const RobotsTxtOutput(),

site/lib/src/components/common/prev_next.dart

@@ -5,15 +5,16 @@
 import 'package:jaspr/jaspr.dart';
 
 import '../../markdown/markdown_parser.dart';
+import '../../models/page_navigation_model.dart';
 import 'material_icon.dart';
 
 /// Previous and next page buttons to display at the end of a page
 /// in a connected series of pages, such as the language docs.
 class PrevNext extends StatelessComponent {
   const PrevNext({super.key, this.previousPage, this.nextPage});
 
-  final ({String url, String title})? previousPage;
-  final ({String url, String title})? nextPage;
+  final PageNavigationEntry? previousPage;
+  final PageNavigationEntry? nextPage;
 
   @override
   Component build(BuildContext context) {
@@ -33,7 +34,7 @@ class PrevNext extends StatelessComponent {
 class _PrevNextCard extends StatelessComponent {
   const _PrevNextCard({required this.page, required this.isPrevious});
 
-  final ({String url, String title}) page;
+  final PageNavigationEntry page;
   final bool isPrevious;
 
   @override

site/lib/src/components/layout/client/pagenav.dart

@@ -7,19 +7,24 @@ import 'package:universal_web/js_interop.dart';
 import 'package:universal_web/web.dart' as web;
 
 import '../../../client/global_scripts.dart';
+import '../../../util.dart';
 import '../../common/dropdown.dart';
 import '../../common/material_icon.dart';
 import '../../util/component_ref.dart';
 
 @client
 class PageNav extends StatefulComponent {
   const PageNav({
-    required this.title,
+    this.breadcrumbs = const [],
+    this.pageNumber,
+    required this.initialHeading,
     required this.content,
     super.key,
   });
 
-  final String title;
+  final List<String> breadcrumbs;
+  final int? pageNumber;
+  final String initialHeading;
   final ComponentRef content;
 
   @override
@@ -63,21 +68,45 @@ class _PageNavState extends State<PageNav> {
           'aria-label': 'Toggle the table of contents dropdown',
         },
         [
-          span(classes: 'toc-intro', [
-            const MaterialIcon('list'),
-            span(
-              attributes: {'aria-label': 'On this page'},
-              [
-                text('On this page'),
-              ],
-            ),
-          ]),
+          const MaterialIcon('list'),
+          if (component.breadcrumbs.isEmpty)
+            span(classes: 'toc-breadcrumb', [
+              span(
+                attributes: {'aria-label': 'On this page'},
+                [text('On this page')],
+              ),
+              const MaterialIcon('chevron_right'),
+            ])
+          else ...[
+            for (final (index, crumb) in component.breadcrumbs.indexed) ...[
+              span(
+                classes: [
+                  'toc-breadcrumb',
+                  if (index < component.breadcrumbs.length - 2)
+                    'toc-hide-medium',
+                  if (index < component.breadcrumbs.length - 1)
+                    'toc-hide-small',
+                ].toClasses,
+                [
+                  if (index == component.breadcrumbs.length - 1 &&
+                      component.pageNumber != null)
+                    span(classes: 'page-number', [
+                      text('${component.pageNumber}'),
+                    ]),
+                  span([
+                    _simpleInlineMarkdown(crumb),
+                  ]),
+                  const MaterialIcon('chevron_right'),
+                ],
+              ),
+            ],
+          ],
+
           span(classes: 'toc-current', [
-            const MaterialIcon('chevron_right'),
             ValueListenableBuilder(
               listenable: currentPageHeading,
               builder: (context, value) {
-                return span([text(value ?? component.title)]);
+                return span([text(value ?? component.initialHeading)]);
               },
             ),
           ]),
@@ -86,4 +115,33 @@ class _PageNavState extends State<PageNav> {
       content: component.content.component,
     );
   }
+
+  /// Simple (and incomplete) implementation of inline markdown parsing
+  /// for use on the client.
+  Component _simpleInlineMarkdown(String content) {
+    final syntaxRegex = RegExp(r'`([^`]+)`|\*([^*]+)\*|\*\*([^*]+)\*\*');
+
+    final components = <Component>[];
+
+    var current = 0;
+    final matches = syntaxRegex.allMatches(content);
+
+    for (final match in matches) {
+      if (match.start > current) {
+        components.add(text(content.substring(current, match.start)));
+      }
+      if (match.group(1) != null) {
+        components.add(code([text(match.group(1)!)]));
+      } else if (match.group(2) != null) {
+        components.add(em([text(match.group(2)!)]));
+      } else if (match.group(3) != null) {
+        components.add(strong([text(match.group(3)!)]));
+      }
+      current = match.end;
+    }
+    if (current < content.length) {
+      components.add(text(content.substring(current)));
+    }
+    return components.length > 1 ? fragment(components) : components.first;
+  }
 }