flutter · parlough · Apr 7, 2026 · Apr 8, 2026 · Apr 8, 2026 · Apr 8, 2026
@@ -0,0 +1,48 @@
+# site_shared
+
+This package is the core library containing
+shared logic, UI components, and the design system for
+the Dart and Flutter documentation sites.
+
+It provides a centralized location for APIs,
+user interface elements, and logic intended for use by
+both the `dart.dev` and `docs.flutter.dev` websites.
+Using a shared package ensures a consistent design language and
+feature set across Dart and Flutter web documentation platforms.
+
+## What's included
+
+The `site_shared` package provides several key capabilities to
+build documentation websites using Dart, Jaspr, and Jaspr Content:
+
+- **UI components** (`lib/components`):
+  Reusable, modular components built for use across documentation pages.
+  - **Common components** (`lib/components/common`):
+    Everyday UI elements such as breadcrumbs, buttons, code blocks, and more.
+  - **Layout components** (`lib/components/layout`):
+    Structural layout elements like theme switchers,
+    site switchers, banners, and menu toggles.
+  - **Interactive components**:
+    Integrations such as Dartpad (`lib/components/dartpad`),
+    tutorials, and user client-side feedback tools.
+- **Markdown extensions and processors** (`lib/extensions`):
+  Custom processors that hook into the Dart Markdown parser to
+  extend its default syntax and behavior, such as `attribute_processor.dart`.
+- **Core styles** (`lib/_sass`):
+  The shared base styles and component-specific SCSS styling.
+  These resources define the unified visual identity used by both websites.
+- **Utilities and builders** (`lib/src`):
+  Reusable logic for code syntax highlighting (`lib/src/highlight`),
+  analytics integrations (`lib/src/analytics`),
+  builders (`lib/src/builders`), and various helper utilities.
+
+## Goals
+
+The primary aims of this shared package are to:
+
+1.  Streamline styling and standardize UI component implementation
+    across our various websites.
+1.  Prevent code duplication between the
+    `dart-lang/site-www` and `flutter/website` repositories.
+1.  Establish a robust codebase that can be
+    updated, maintained, and improved in a unified way.
@@ -0,0 +1,4 @@
+include: package:analysis_defaults/analysis.yaml
+
+formatter:
+  trailing_commas: preserve
@@ -0,0 +1,14 @@
+builders:
+  stylesHashBuilder:
+    import: "package:site_shared/src/builders/styles_hash_builder.dart"
+    builder_factories: ["stylesHashBuilder"]
+    build_extensions:
+      "web/assets/css/main.css":
+        - "lib/src/style_hash.dart"
+    auto_apply: dependents
+    build_to: source
+    required_inputs:
+      - ".css"
+    defaults:
+      dev_options:
+        fixed_hash: true
@@ -25,7 +25,8 @@ button {
   cursor: pointer;
 
   &.filled-button,
-  &.text-button, &.outlined-button {
+  &.text-button,
+  &.outlined-button {
     display: flex;
     align-items: center;
     width: fit-content;

@@ -173,7 +173,7 @@
     }
   }
 
-    &.install-card {
+  &.install-card {
     gap: 0.25rem;
 
     .card-leading {

@@ -0,0 +1,26 @@
+// Toggle between menu and close buttons if sidenav is open or not.
+body:not(.sidenav-closed) #menu-toggle {
+  @media (min-width: 1024px) {
+    display: none;
+  }
+}
+
+#menu-toggle span.material-symbols {
+  &:first-child {
+    display: inline;
+  }
+
+  &:last-child {
+    display: none;
+  }
+}
+
+body.open_menu #menu-toggle span.material-symbols {
+  &:first-child {
+    display: none;
+  }
+
+  &:last-child {
+    display: inline;
+  }
+}
@@ -0,0 +1,14 @@
+.progress-ring {
+  circle {
+    fill: none;
+    stroke-linecap: round;
+  }
+
+  .ring-inactive {
+    stroke: var(--site-inset-borderColor);
+  }
+
+  .ring-active {
+    stroke: var(--site-primary-color);
+  }
+}
@@ -1,5 +1,3 @@
-@use '../base/mixins';
-
 #site-switcher {
   position: relative;
 

@@ -44,7 +44,7 @@
   }
 
   // On non-touch devices, show tooltip on hover or focus.
-  @media all and not (pointer: coarse) {
+  @media all and (not (pointer: coarse)) {
     &:hover .tooltip {
       visibility: visible;
     }
@@ -60,4 +60,4 @@
       visibility: visible;
     }
   }
-}
+}
@@ -2,19 +2,18 @@
 // 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';
+import 'src/analytics/analytics_server.dart'
+    if (dart.library.js_interop) 'src/analytics/analytics_web.dart';
 
 /// Used to report analytic events.
-final analytics = AnalyticsImplementation();
+final Analytics analytics = AnalyticsImplementation();
 
-/// Contains methods for reporting analytics events.
+/// Used for reporting analytics events.
 abstract class Analytics {
-  @internal
+  /// Reports an event named [eventName], along with the specified [parameters].
   void sendEvent(String eventName, Map<String, Object?> parameters);
 
+  /// Reports whether the user found the current page [helpful].
   void sendFeedback(bool helpful) {
     sendEvent('feedback', {'feedback_type': helpful ? 'up' : 'down'});
   }

@@ -18,11 +18,14 @@ import 'material_icon.dart';
 /// - https://schema.org/BreadcrumbList
 /// - https://www.w3.org/TR/wai-aria-practices/examples/breadcrumb/index.html
 class PageBreadcrumbs extends StatelessComponent {
-  const PageBreadcrumbs({super.key});
+  const PageBreadcrumbs({this.crumbs, super.key});
+
+  final List<BreadcrumbItem>? crumbs;
 
   @override
   Component build(BuildContext context) {
-    final crumbs = _breadcrumbsForPage(context.pages, context.page);
+    final crumbs =
+        this.crumbs ?? _breadcrumbsForPage(context.pages, context.page);
     if (crumbs == null || crumbs.isEmpty) {
       return const Component.empty();
     }
@@ -54,7 +57,7 @@ class PageBreadcrumbs extends StatelessComponent {
   ///
   /// Uses page metadata to generate breadcrumb titles with fallbacks:
   /// `breadcrumb` > `shortTitle` > `title`.
-  List<_BreadcrumbItem>? _breadcrumbsForPage(List<Page> pages, Page page) {
+  List<BreadcrumbItem>? _breadcrumbsForPage(List<Page> pages, Page page) {
     final pageUrl = page.url;
 
     // Only show breadcrumbs if the URL isn't empty.
@@ -71,7 +74,7 @@ class PageBreadcrumbs extends StatelessComponent {
         .toList(growable: false);
     if (segments.isEmpty) return null;
 
-    final breadcrumbs = <_BreadcrumbItem>[];
+    final breadcrumbs = <BreadcrumbItem>[];
     var currentPath = '';
 
     // Build breadcrumbs for each segment except the current page.
@@ -88,7 +91,7 @@ class PageBreadcrumbs extends StatelessComponent {
 
       if (indexPage.breadcrumb case final indexBreadcrumb?) {
         breadcrumbs.add(
-          _BreadcrumbItem(
+          BreadcrumbItem(
             title: indexBreadcrumb,
             url: indexPage.url,
           ),
@@ -104,7 +107,7 @@ class PageBreadcrumbs extends StatelessComponent {
 
     // Add the current page as the final breadcrumb.
     breadcrumbs.add(
-      _BreadcrumbItem(
+      BreadcrumbItem(
         title: pageBreadcrumb,
         url: pageUrl,
       ),
@@ -127,8 +130,8 @@ extension on Page {
   }
 }
 
-final class _BreadcrumbItem {
-  const _BreadcrumbItem({required this.title, required this.url});
+final class BreadcrumbItem {
+  const BreadcrumbItem({required this.title, required this.url});
 
   final String title;
   final String url;
@@ -142,7 +145,7 @@ final class _BreadcrumbItemComponent extends StatelessComponent {
     required this.isLast,
   });
 
-  final _BreadcrumbItem crumb;
+  final BreadcrumbItem crumb;
   final int index;
   final bool isLast;
 

@@ -14,6 +14,7 @@ class Button extends StatelessComponent {
   const Button({
     super.key,
     this.icon,
+    this.trailingIcon,
     this.href,
     this.content,
     this.style = ButtonStyle.text,
@@ -30,6 +31,7 @@ class Button extends StatelessComponent {
   final String? title;
   final ButtonStyle style;
   final String? icon;
+  final String? trailingIcon;
   final String? id;
   final String? href;
   final Map<String, String> attributes;
@@ -48,14 +50,16 @@ class Button extends StatelessComponent {
 
     final mergedClasses = [
       style.cssClass,
-      if (icon != null && content == null) 'icon-button',
+      if ((icon != null || trailingIcon != null) && content == null)
+        'icon-button',
       ...?classes,
     ].toClasses;
 
     final children = <Component>[
       if (icon case final iconId?) MaterialIcon(iconId),
       if (content case final contentText?)
         asRaw ? RawText(contentText) : .text(contentText),
+      if (trailingIcon case final iconId?) MaterialIcon(iconId),
     ];
 
     if (href case final href?) {
@@ -90,17 +94,3 @@ enum ButtonStyle {
     ButtonStyle.text => 'text-button',
   };
 }
-
-class SegmentedButton extends StatelessComponent {
-  const SegmentedButton({
-    super.key,
-    required this.children,
-  });
-
-  final List<Component> children;
-
-  @override
-  Component build(BuildContext context) {
-    return span(classes: ['segmented-button'].toClasses, children);
-  }
-}
@@ -7,7 +7,7 @@ import 'package:jaspr/jaspr.dart';
 import 'package:universal_web/web.dart' as web;
 
 import '../../util.dart';
-import '../util/global_event_listener.dart';
+import '../utils/global_event_listener.dart';
 import 'material_icon.dart';
 
 /// A set of Material Design-like chips for configuration.

@@ -3,7 +3,6 @@
 // found in the LICENSE file.
 
 import 'package:jaspr/jaspr.dart';
-
 import 'package:universal_web/web.dart' as web;
 
 import '../button.dart';

@@ -12,7 +12,14 @@ import '../button.dart';
 /// The cookie banner to show on a user's first time visiting the site.
 @client
 final class CookieNotice extends StatefulComponent {
-  const CookieNotice({super.key});
+  const CookieNotice({
+    super.key,
+    required this.host,
+    this.alwaysDarkMode = false,
+  });
+
+  final String host;
+  final bool alwaysDarkMode;
 
   @override
   State<CookieNotice> createState() => _CookieNoticeState();
@@ -60,13 +67,16 @@ final class _CookieNoticeState extends State<CookieNotice> {
   Component build(BuildContext context) {
     return section(
       id: 'cookie-notice',
-      classes: [if (showNotice) 'show'].toClasses,
+      classes: [
+        if (showNotice) 'show',
+        if (component.alwaysDarkMode) 'always-dark-mode',
+      ].toClasses,
       attributes: {'data-nosnippet': 'true'},
       [
         div(classes: 'container', [
-          const p([
+          p([
             .text(
-              'docs.flutter.dev uses cookies from Google to deliver and '
+              '${component.host} uses cookies from Google to deliver and '
               'enhance the quality of its services and to analyze traffic.',
             ),
           ]),