add providerBuilder for sign in and register screen layout customization

Author: fabiocarneiro

.gitignore

@@ -78,3 +78,4 @@ firebase-debug.log
 firestore-debug.log
 database-debug.log
 ui-debug.log
+conductor/

packages/firebase_ui_auth/lib/src/screens/internal/login_screen.dart

@@ -57,6 +57,9 @@ class LoginScreen extends StatelessWidget {
   /// {@macro ui.auth.screens.responsive_page.max_width}
   final double? maxWidth;
 
+  /// A builder that allows to customize the order and appearance of the providers.
+  final ProvidersBuilder? providersBuilder;
+
   const LoginScreen({
     super.key,
     required this.action,
@@ -77,6 +80,7 @@ class LoginScreen extends StatelessWidget {
     this.styles,
     this.showPasswordVisibilityToggle = false,
     this.maxWidth,
+    this.providersBuilder,
   });
 
   @override
@@ -96,6 +100,7 @@ class LoginScreen extends StatelessWidget {
           subtitleBuilder: subtitleBuilder,
           footerBuilder: footerBuilder,
           showPasswordVisibilityToggle: showPasswordVisibilityToggle,
+          providersBuilder: providersBuilder,
         ),
       ),
     );

packages/firebase_ui_auth/lib/src/screens/register_screen.dart

@@ -93,6 +93,12 @@ class RegisterScreen extends MultiProviderScreen {
   /// {@macro ui.auth.screens.responsive_page.max_width}
   final double? maxWidth;
 
+  /// A builder that allows to customize the order and appearance of the providers.
+  ///
+  /// If not provided, the default explicit order is used:
+  /// Email, Phone, Email Link, OAuth.
+  final ProvidersBuilder? providersBuilder;
+
   const RegisterScreen({
     super.key,
     super.auth,
@@ -112,6 +118,7 @@ class RegisterScreen extends MultiProviderScreen {
     this.styles,
     this.showPasswordVisibilityToggle = false,
     this.maxWidth,
+    this.providersBuilder,
   });
 
   @override
@@ -136,6 +143,7 @@ class RegisterScreen extends MultiProviderScreen {
         breakpoint: breakpoint,
         showPasswordVisibilityToggle: showPasswordVisibilityToggle,
         maxWidth: maxWidth,
+        providersBuilder: providersBuilder,
       ),
     );
   }

packages/firebase_ui_auth/lib/src/screens/sign_in_screen.dart

@@ -101,6 +101,12 @@ class SignInScreen extends MultiProviderScreen {
   /// {@macro ui.auth.screens.responsive_page.max_width}
   final double? maxWidth;
 
+  /// A builder that allows to customize the order and appearance of the providers.
+  ///
+  /// If not provided, the default explicit order is used:
+  /// Email, Phone, Email Link, OAuth.
+  final ProvidersBuilder? providersBuilder;
+
   /// {@macro ui.auth.screens.sign_in_screen}
   const SignInScreen({
     super.key,
@@ -122,6 +128,7 @@ class SignInScreen extends MultiProviderScreen {
     this.styles,
     this.showPasswordVisibilityToggle = false,
     this.maxWidth,
+    this.providersBuilder,
   });
 
   @override
@@ -151,6 +158,7 @@ class SignInScreen extends MultiProviderScreen {
         breakpoint: breakpoint,
         showPasswordVisibilityToggle: showPasswordVisibilityToggle,
         maxWidth: maxWidth,
+        providersBuilder: providersBuilder,
       ),
     );
   }

packages/firebase_ui_auth/lib/src/views/login_view.dart

@@ -18,6 +18,12 @@ typedef AuthViewContentBuilder = Widget Function(
   AuthAction action,
 );
 
+typedef ProvidersBuilder = List<Widget> Function(
+  BuildContext context,
+  List<AuthProvider> providers,
+  AuthAction action,
+);
+
 /// {@template ui.auth.views.login_view}
 /// A view that could be used to build a custom [SignInScreen] or
 /// [RegisterScreen].
@@ -58,6 +64,12 @@ class LoginView extends StatefulWidget {
   /// {@macro ui.auth.widgets.email_from.showPasswordVisibilityToggle}
   final bool showPasswordVisibilityToggle;
 
+  /// A builder that allows to customize the order and appearance of the providers.
+  ///
+  /// If not provided, the default explicit order is used:
+  /// Email, Phone, Email Link, OAuth.
+  final ProvidersBuilder? providersBuilder;
+
   /// {@macro ui.auth.views.login_view}
   const LoginView({
     super.key,
@@ -72,6 +84,7 @@ class LoginView extends StatefulWidget {
     this.subtitleBuilder,
     this.actionButtonLabelOverride,
     this.showPasswordVisibilityToggle = false,
+    this.providersBuilder,
   });
 
   @override
@@ -204,53 +217,92 @@ class _LoginViewState extends State<LoginView> {
     super.didUpdateWidget(oldWidget);
   }
 
+  Widget? _buildProviderWidget(TargetPlatform platform, AuthProvider provider) {
+    final l = FirebaseUILocalizations.labelsOf(context);
+
+    if (provider is EmailAuthProvider) {
+      return EmailForm(
+        key: ValueKey(_action),
+        auth: widget.auth,
+        action: _action,
+        provider: provider,
+        email: widget.email,
+        actionButtonLabelOverride: widget.actionButtonLabelOverride,
+        showPasswordVisibilityToggle: widget.showPasswordVisibilityToggle,
+      );
+    } else if (provider is PhoneAuthProvider) {
+      return PhoneVerificationButton(
+        label: l.signInWithPhoneButtonText,
+        action: _action,
+        auth: widget.auth,
+      );
+    } else if (provider is EmailLinkAuthProvider) {
+      return EmailLinkSignInButton(
+        auth: widget.auth,
+        provider: provider,
+      );
+    } else if (provider is OAuthProvider && !_buttonsBuilt) {
+      return _buildOAuthButtons(platform);
+    }
+    return null;
+  }
+
+  List<Widget> _defaultProvidersBuilder(
+    BuildContext context,
+    List<AuthProvider> providers,
+    AuthAction action,
+  ) {
+    final platform = Theme.of(context).platform;
+    final children = <Widget>[];
+
+    void addForType<T>() {
+      for (var provider in providers) {
+        if (provider is T && provider.supportsPlatform(platform)) {
+          final w = _buildProviderWidget(platform, provider);
+
+          if (w != null) {
+            if (provider is OAuthProvider) {
+              children.add(w);
+            } else {
+              children.add(const SizedBox(height: 8));
+              children.add(w);
+              if (provider is PhoneAuthProvider) {
+                children.add(const SizedBox(height: 8));
+              }
+            }
+          }
+        }
+      }
+    }
+
+    addForType<EmailAuthProvider>();
+    addForType<PhoneAuthProvider>();
+    addForType<EmailLinkAuthProvider>();
+    addForType<OAuthProvider>();
+
+    return children;
+  }
+
   @override
   Widget build(BuildContext context) {
-    final l = FirebaseUILocalizations.labelsOf(context);
     final platform = Theme.of(context).platform;
     _buttonsBuilt = false;
 
+    final children = <Widget>[
+      if (_showTitle) ..._buildHeader(context),
+    ];
+
+    final builder = widget.providersBuilder ?? _defaultProvidersBuilder;
+    children.addAll(builder(context, widget.providers, _action));
+
+    if (widget.footerBuilder != null) {
+      children.add(widget.footerBuilder!(context, _action));
+    }
+
     return IntrinsicHeight(
       child: Column(
         crossAxisAlignment: CrossAxisAlignment.stretch,
-        children: [
-          if (_showTitle) ..._buildHeader(context),
-          for (var provider in widget.providers)
-            if (provider.supportsPlatform(platform))
-              if (provider is EmailAuthProvider) ...[
-                const SizedBox(height: 8),
-                EmailForm(
-                  key: ValueKey(_action),
-                  auth: widget.auth,
-                  action: _action,
-                  provider: provider,
-                  email: widget.email,
-                  actionButtonLabelOverride: widget.actionButtonLabelOverride,
-                  showPasswordVisibilityToggle:
-                      widget.showPasswordVisibilityToggle,
-                )
-              ] else if (provider is PhoneAuthProvider) ...[
-                const SizedBox(height: 8),
-                PhoneVerificationButton(
-                  label: l.signInWithPhoneButtonText,
-                  action: _action,
-                  auth: widget.auth,
-                ),
-                const SizedBox(height: 8),
-              ] else if (provider is EmailLinkAuthProvider) ...[
-                const SizedBox(height: 8),
-                EmailLinkSignInButton(
-                  auth: widget.auth,
-                  provider: provider,
-                ),
-              ] else if (provider is OAuthProvider && !_buttonsBuilt)
-                _buildOAuthButtons(platform),
-          if (widget.footerBuilder != null)
-            widget.footerBuilder!(
-              context,
-              _action,
-            ),
-        ],
+        children: children,
       ),
     );
   }

packages/firebase_ui_auth/test/screens/register_screen_providers_builder_test.dart

@@ -0,0 +1,32 @@
+// Copyright 2024, the Chromium project authors.  Please see the AUTHORS file
+// for details. 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:firebase_ui_auth/firebase_ui_auth.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import '../test_utils.dart';
+
+void main() {
+  group('RegisterScreen providersBuilder', () {
+    setUpAll(() {
+      setFirebaseUiIsTestMode(true);
+    });
+
+    testWidgets('propagates providersBuilder to LoginView', (tester) async {
+      await tester.pumpWidget(
+        TestMaterialApp(
+          child: RegisterScreen(
+            auth: MockAuth(),
+            providers: [EmailAuthProvider()],
+            providersBuilder: (context, providers, action) {
+              return [const Text('Custom Register Builder')];
+            },
+          ),
+        ),
+      );
+
+      expect(find.text('Custom Register Builder'), findsOneWidget);
+    });
+  });
+}

packages/firebase_ui_auth/test/screens/sign_in_screen_providers_builder_test.dart

@@ -0,0 +1,32 @@
+// Copyright 2024, the Chromium project authors.  Please see the AUTHORS file
+// for details. 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:firebase_ui_auth/firebase_ui_auth.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import '../test_utils.dart';
+
+void main() {
+  group('SignInScreen providersBuilder', () {
+    setUpAll(() {
+      setFirebaseUiIsTestMode(true);
+    });
+
+    testWidgets('propagates providersBuilder to LoginView', (tester) async {
+      await tester.pumpWidget(
+        TestMaterialApp(
+          child: SignInScreen(
+            auth: MockAuth(),
+            providers: [EmailAuthProvider()],
+            providersBuilder: (context, providers, action) {
+              return [const Text('Custom SignIn Builder')];
+            },
+          ),
+        ),
+      );
+
+      expect(find.text('Custom SignIn Builder'), findsOneWidget);
+    });
+  });
+}

packages/firebase_ui_auth/test/views/login_view_providers_builder_test.dart

@@ -0,0 +1,70 @@
+// Copyright 2024, the Chromium project authors.  Please see the AUTHORS file
+// for details. 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:firebase_ui_auth/firebase_ui_auth.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import '../test_utils.dart';
+
+void main() {
+  group('LoginView providersBuilder', () {
+    testWidgets('uses custom providersBuilder when provided', (tester) async {
+      await tester.pumpWidget(
+        TestMaterialApp(
+          child: LoginView(
+            auth: MockAuth(),
+            action: AuthAction.signIn,
+            providers: [
+              EmailAuthProvider(),
+              PhoneAuthProvider(),
+            ],
+            providersBuilder: (context, providers, action) {
+              return [
+                const Text('Custom Header'),
+                for (final provider in providers)
+                   if (provider is EmailAuthProvider)
+                     const Text('Custom Email Form'),
+              ];
+            },
+          ),
+        ),
+      );
+
+      expect(find.text('Custom Header'), findsOneWidget);
+      expect(find.text('Custom Email Form'), findsOneWidget);
+      // Phone provider should be ignored as per our custom builder logic
+      expect(find.byType(PhoneVerificationButton), findsNothing);
+    });
+
+    testWidgets('uses default explicit order when no builder provided', (tester) async {
+      await tester.pumpWidget(
+        TestMaterialApp(
+          child: LoginView(
+            auth: MockAuth(),
+            action: AuthAction.signIn,
+            providers: [
+              PhoneAuthProvider(), // Phone first in list
+              EmailAuthProvider(), // Email second
+            ],
+          ),
+        ),
+      );
+
+      // But default explicit order should be Email then Phone (if we strictly follow the new spec)
+      // The spec says: "If no providersBuilder is provided, the system should use a default explicit order: [Email, Phone, EmailLink, OAuth]."
+      
+      final emailFinder = find.byType(EmailForm);
+      final phoneFinder = find.byType(PhoneVerificationButton);
+
+      expect(emailFinder, findsOneWidget);
+      expect(phoneFinder, findsOneWidget);
+
+      final emailTop = tester.getTopLeft(emailFinder).dy;
+      final phoneTop = tester.getTopLeft(phoneFinder).dy;
+
+      // Verify explicit default order: Email should be above Phone
+      expect(emailTop, lessThan(phoneTop));
+    });
+  });
+}