Add ProgressRing component for FWE (#12674)

Adds a material3 style progress ring, for use in FWE.

<img width="271" height="149" alt="Bildschirmfoto 2025-11-12 um 15 37
30"
src="https://github.com/user-attachments/assets/b73a96ed-d8a1-46e2-bedf-bf56c6335646"
/>

Author: schultek

site/lib/_sass/components/_misc.scss

@@ -77,3 +77,18 @@
     }
   }
 }
+
+.progress-ring {
+  circle {
+    fill: none;
+    stroke-linecap: round;
+  }
+
+  .ring-inactive {
+    stroke: var(--site-inset-borderColor);
+  }
+
+  .ring-active {
+    stroke: var(--site-primary-color);
+  }
+}

site/lib/main.dart

@@ -19,6 +19,7 @@ import 'src/components/pages/archive_table.dart';
 import 'src/components/pages/devtools_release_notes_index.dart';
 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/extensions/registry.dart';
 import 'src/layouts/catalog_page_layout.dart';
@@ -98,6 +99,7 @@ List<CustomComponent> get _embeddableComponents => [
   const YoutubeEmbed(),
   const FileTree(),
   const Quiz(),
+  const ProgressRing(),
   CustomComponent(
     pattern: RegExp('OSSelector', caseSensitive: false),
     builder: (_, _, _) => const OsSelector(),

site/lib/src/components/tutorial/client/progress_ring.dart

@@ -0,0 +1,87 @@
+// Copyright 2025 The Flutter Authors. 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:math';
+
+import 'package:jaspr/jaspr.dart';
+
+class InteractiveProgressRing extends StatelessComponent {
+  const InteractiveProgressRing({required this.progress, required this.size})
+    : assert(progress >= 0.0 && progress <= 1.0);
+
+  final double progress;
+  final double size;
+
+  @override
+  Component build(BuildContext context) {
+    // The radius of the ring.
+    const r = 24;
+    // The stroke width of the ring.
+    const strokeWidth = 4;
+    // The full circumference of the ring.
+    const full = pi * r * 2;
+    // Offset to start drawing at 12 o'clock, since default strokes
+    // start at 3 o'clock.
+    const quarter = full / 4;
+    // The absolute gap between active and inactive tracks.
+    const gap = strokeWidth * 2;
+    // The relative gap as a factor of the full circumference.
+    const rGap = gap / full;
+
+    // Adjust progress to precicely align with each quarter of the ring
+    // while accounting for the visual gap (reversing the stroke offset logic)
+    // and keeping a continuous curve to each limit (0 and 1).
+    final adjustedProgress =
+        progress -
+        switch (progress) {
+          //        (== 0 for prog -> 0; == gap for prog -> 0.25)
+          < 0.25 => (progress * 4 * rGap),
+          //        (== gap for prog -> 0.75; == 0 for prog -> 1)
+          > 0.75 => (1 - progress) * 4 * rGap,
+          _ => rGap,
+        };
+
+    // Absolute lengths of the active and inactive portions of the ring.
+    final inactiveLength = (1 - adjustedProgress) * full - gap * 2;
+    final activeLength = adjustedProgress * full;
+
+    return svg(
+      classes: 'progress-ring',
+      width: size.px,
+      height: size.px,
+      viewBox: '0 0 ${r * 2 + strokeWidth} ${r * 2 + strokeWidth}',
+      [
+        // For values close to 1, inactiveLength can become <=0 due to gap.
+        if (inactiveLength > 0)
+          // Inactive portion, drawn from (progress)° to (0)°
+          circle(
+            classes: 'ring-inactive',
+            cx: '${r + strokeWidth / 2}',
+            cy: '${r + strokeWidth / 2}',
+            r: '$r',
+            strokeWidth: strokeWidth.toString(),
+            attributes: {
+              'stroke-dasharray': '$inactiveLength ${full - inactiveLength}',
+              'stroke-dashoffset': '${quarter - activeLength - gap * 1.5}',
+            },
+            [],
+          ),
+
+        // Active portion, drawn from 0° to (progress)°
+        circle(
+          classes: 'ring-active',
+          cx: '${r + strokeWidth / 2}',
+          cy: '${r + strokeWidth / 2}',
+          r: '$r',
+          strokeWidth: strokeWidth.toString(),
+          attributes: {
+            'stroke-dasharray': '$activeLength ${full - activeLength}',
+            'stroke-dashoffset': '${quarter - gap / 2}',
+          },
+          [],
+        ),
+      ],
+    );
+  }
+}

site/lib/src/components/tutorial/progress_ring.dart

@@ -0,0 +1,40 @@
+// Copyright 2025 The Flutter Authors. 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 'package:jaspr_content/jaspr_content.dart';
+
+import 'client/progress_ring.dart';
+
+class ProgressRing extends CustomComponentBase {
+  const ProgressRing();
+
+  @override
+  Pattern get pattern => RegExp('ProgressRing', caseSensitive: false);
+
+  @override
+  Component apply(
+    String name,
+    Map<String, String> attributes,
+    Component? child,
+  ) {
+    final progress = double.tryParse(attributes['progress'] ?? '') ?? 0.0;
+    assert(
+      progress >= 0.0 && progress <= 1.0,
+      'ProgressRing progress must be between 0.0 and 1.0',
+    );
+
+    final small = attributes['small'] != null;
+    final large = attributes['large'] != null;
+
+    return InteractiveProgressRing(
+      progress: progress,
+      size: small
+          ? 24
+          : large
+          ? 48
+          : 32,
+    );
+  }
+}

site/lib/src/pages/custom_pages.dart

@@ -78,6 +78,8 @@ description: This is a test page for experimenting with First Week Experience (F
 sitemap: false
 ---
 
+## Quiz
+
 <Quiz title="Flutter and Dart Basics Quiz">
 - question: What is the Effective Dart guideline for the first sentence of a documentation comment?
   options:
@@ -108,5 +110,21 @@ sitemap: false
       correct: false
       explanation: Stack is used for overlapping widgets, not for scrollable lists.
 </Quiz>
+
+## Progress Ring
+
+<ProgressRing progress="0.0" />
+<ProgressRing progress="0.25" />
+<ProgressRing progress="0.5" />
+<ProgressRing progress="0.75" />
+<ProgressRing progress="1.0" />
+
+---
+
+<ProgressRing progress="0.1" small />
+<ProgressRing progress="0.6" small />
+<ProgressRing progress="0.3" large />
+<ProgressRing progress="0.95" large />
+
 ''',
 );

site/lib/src/style_hash.dart

@@ -2,4 +2,4 @@
 // dart format off
 
 /// The generated hash of the `main.css` file.
-const generatedStylesHash = 'URzUaI467vwY';
+const generatedStylesHash = 'm+c3m5q1zKUq';