Merge branch 'learn-fb' into integration

packages/halkyon_ui/lib/halkyon_ui.dart

@@ -22,6 +22,7 @@ export 'src/widget/confirm_dialog.dart';
 export 'src/widget/count_badge.dart';
 export 'src/widget/count_stepper.dart';
 export 'src/widget/empty_list_message.dart';
+export 'src/widget/explained_title.dart';
 export 'src/widget/field_label.dart';
 export 'src/widget/floating_navigation_bar.dart';
 export 'src/widget/folding_tabs.dart';

packages/halkyon_ui/lib/src/widget/explained_title.dart

@@ -0,0 +1,22 @@
+import 'package:halkyon_ui/src/widget/help_button.dart';
+import 'package:material_ui/material_ui.dart';
+
+/// A section's or a setting's [title] with its [HelpButton] right beside
+/// it, opening [help] under the title (decided 3 Nov 2026: what explains
+/// is one tap away). In [style] where given, the surrounding text's
+/// otherwise, as a [ListTile]'s title; a long title wraps, the question
+/// mark kept beside its end.
+class const ExplainedTitle(
+  final String title, {
+  required final String help,
+  final TextStyle? style,
+  super.key,
+}) extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) => Row(
+    children: [
+      Flexible(child: Text(title, style: style)),
+      HelpButton(help, title: title),
+    ],
+  );
+}

packages/halkyon_ui/test/widget/explained_title_test.dart

@@ -0,0 +1,52 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:halkyon_ui/halkyon_ui.dart';
+import 'package:material_ui/material_ui.dart';
+
+import '../support/test_app.dart';
+
+void main() {
+  testWidgets('a title with its question mark right beside it, the '
+      'explanation opening under the title', (tester) async {
+    await tester.pumpWidget(
+      testApp(
+        const Scaffold(
+          body: SizedBox(
+            width: 300,
+            child: ListTile(
+              title: ExplainedTitle(
+                'Check spelling',
+                help: 'Underlines possible mistakes.',
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
+    expect(find.text('Underlines possible mistakes.'), findsNothing);
+    final title = tester.getRect(find.text('Check spelling'));
+    final help = tester.getRect(find.byType(HelpButton));
+    expect(help.left - title.right, lessThan(8), reason: 'beside it');
+
+    await tester.tap(find.byType(HelpButton));
+    await tester.pumpAndSettle();
+    expect(find.text('Check spelling'), findsNWidgets(2));
+    expect(find.text('Underlines possible mistakes.'), findsOneWidget);
+  });
+
+  testWidgets('a long title wraps, its question mark kept', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      testApp(
+        Scaffold(
+          body: SizedBox(
+            width: 200,
+            child: ExplainedTitle('A title ' * 20, help: 'Why.'),
+          ),
+        ),
+      ),
+    );
+    expect(tester.takeException(), isNull);
+    expect(find.byType(HelpButton), findsOneWidget);
+  });
+}