refactor: Improve Dialog UX

- Add Recovery by email in postJoin dialogs
- Add an option to let player in to recover in preJoin
- Add customizable body description

Author: Xephi

authme-core/src/main/java/fr/xephi/authme/message/MessageKey.java

@@ -242,9 +242,21 @@ public enum MessageKey {
     /** Login dialog submit button label. */
     DIALOG_LOGIN_BUTTON("dialog.login.button"),
 
+    /** Login dialog body text shown below the title. */
+    DIALOG_LOGIN_BODY("dialog.login.body"),
+
+    /** Login dialog recovery email field label. */
+    DIALOG_LOGIN_RECOVERY_EMAIL("dialog.login.recovery_email"),
+
+    /** Login dialog forgot-password button label. */
+    DIALOG_LOGIN_RECOVERY_BUTTON("dialog.login.recovery_button"),
+
     /** Register dialog title. */
     DIALOG_REGISTER_TITLE("dialog.register.title"),
 
+    /** Register dialog body text shown below the title. */
+    DIALOG_REGISTER_BODY("dialog.register.body"),
+
     /** Register dialog password field label. */
     DIALOG_REGISTER_PASSWORD("dialog.register.password"),
 
@@ -263,6 +275,9 @@ public enum MessageKey {
     /** Two-factor dialog title. */
     DIALOG_TWO_FACTOR_TITLE("dialog.two_factor.title"),
 
+    /** Two-factor dialog body text shown below the title. */
+    DIALOG_TWO_FACTOR_BODY("dialog.two_factor.body"),
+
     /** Two-factor dialog code field label. */
     DIALOG_TWO_FACTOR_CODE("dialog.two_factor.code"),
 

authme-core/src/main/java/fr/xephi/authme/platform/DialogWindowSpec.java

@@ -12,13 +12,18 @@
  * @param secondaryButtonLabel the optional secondary button label
  * @param showSecondaryButton whether a secondary button should be rendered
  * @param canCloseWithEscape whether the dialog may be dismissed with escape when the platform supports it
+ * @param secondaryButtonCommand command template the secondary button should execute in post-join dialogs
+ *                               (null for pre-join dialogs where the secondary button is a cancel action)
+ * @param body optional translated body text shown below the title (null = no body)
  */
 public record DialogWindowSpec(String title,
                                List<DialogInputSpec> inputs,
                                String primaryButtonLabel,
                                String secondaryButtonLabel,
                                boolean showSecondaryButton,
-                               boolean canCloseWithEscape) {
+                               boolean canCloseWithEscape,
+                               String secondaryButtonCommand,
+                               String body) {
 
     public DialogWindowSpec {
         Objects.requireNonNull(title, "title");
@@ -27,4 +32,16 @@ public record DialogWindowSpec(String title,
         Objects.requireNonNull(secondaryButtonLabel, "secondaryButtonLabel");
         inputs = List.copyOf(inputs);
     }
+
+    /** Convenience constructor without body text (body = null). */
+    public DialogWindowSpec(String title,
+                            List<DialogInputSpec> inputs,
+                            String primaryButtonLabel,
+                            String secondaryButtonLabel,
+                            boolean showSecondaryButton,
+                            boolean canCloseWithEscape,
+                            String secondaryButtonCommand) {
+        this(title, inputs, primaryButtonLabel, secondaryButtonLabel,
+            showSecondaryButton, canCloseWithEscape, secondaryButtonCommand, null);
+    }
 }

authme-core/src/main/java/fr/xephi/authme/service/DialogWindowService.java

@@ -32,7 +32,29 @@ public class DialogWindowService {
     }
 
     public DialogWindowSpec createLoginDialog(Player player) {
-        return createLoginDialogSpec(key -> getPostJoinMessage(player, key), false, false);
+        boolean showRecovery = commonService.getProperty(RegistrationSettings.DIALOG_SHOW_FORGOT_PASSWORD_BUTTON);
+        boolean showBody = commonService.getProperty(RegistrationSettings.DIALOG_SHOW_BODY);
+        Function<MessageKey, String> text = key -> getPostJoinMessage(player, key);
+
+        List<DialogInputSpec> inputs = new ArrayList<>();
+        inputs.add(new DialogInputSpec("password",
+            text.apply(MessageKey.DIALOG_LOGIN_PASSWORD),
+            DEFAULT_MAX_INPUT_LENGTH));
+        if (showRecovery) {
+            inputs.add(new DialogInputSpec("email",
+                text.apply(MessageKey.DIALOG_LOGIN_RECOVERY_EMAIL),
+                DEFAULT_MAX_INPUT_LENGTH));
+        }
+
+        return new DialogWindowSpec(
+            text.apply(MessageKey.DIALOG_LOGIN_TITLE),
+            inputs,
+            text.apply(MessageKey.DIALOG_LOGIN_BUTTON),
+            showRecovery ? text.apply(MessageKey.DIALOG_LOGIN_RECOVERY_BUTTON) : text.apply(MessageKey.DIALOG_CANCEL_BUTTON),
+            showRecovery,
+            false,
+            showRecovery ? "email recover $(email)" : null,
+            showBody ? text.apply(MessageKey.DIALOG_LOGIN_BODY) : null);
     }
 
     public DialogWindowSpec createPreJoinLoginDialog(String playerName) {
@@ -42,15 +64,20 @@ public DialogWindowSpec createPreJoinLoginDialog(String playerName) {
     }
 
     public DialogWindowSpec createTotpDialog(Player player) {
+        boolean showBody = commonService.getProperty(RegistrationSettings.DIALOG_SHOW_BODY);
+        Function<MessageKey, String> text = key -> getPostJoinMessage(player, key);
+
         return new DialogWindowSpec(
-            getPostJoinMessage(player, MessageKey.DIALOG_TWO_FACTOR_TITLE),
+            text.apply(MessageKey.DIALOG_TWO_FACTOR_TITLE),
             List.of(new DialogInputSpec("code",
-                getPostJoinMessage(player, MessageKey.DIALOG_TWO_FACTOR_CODE),
+                text.apply(MessageKey.DIALOG_TWO_FACTOR_CODE),
                 TOTP_CODE_MAX_INPUT_LENGTH)),
-            getPostJoinMessage(player, MessageKey.DIALOG_TWO_FACTOR_BUTTON),
-            getPostJoinMessage(player, MessageKey.DIALOG_CANCEL_BUTTON),
+            text.apply(MessageKey.DIALOG_TWO_FACTOR_BUTTON),
+            text.apply(MessageKey.DIALOG_CANCEL_BUTTON),
             false,
-            false);
+            false,
+            null,
+            showBody ? text.apply(MessageKey.DIALOG_TWO_FACTOR_BODY) : null);
     }
 
     public DialogWindowSpec createRegisterDialog(Player player,
@@ -70,6 +97,7 @@ public DialogWindowSpec createPreJoinRegisterDialog(String playerName,
     private DialogWindowSpec createLoginDialogSpec(Function<MessageKey, String> textResolver,
                                                    boolean showSecondaryButton,
                                                    boolean canCloseWithEscape) {
+        boolean showBody = commonService.getProperty(RegistrationSettings.DIALOG_SHOW_BODY);
         return new DialogWindowSpec(
             textResolver.apply(MessageKey.DIALOG_LOGIN_TITLE),
             List.of(new DialogInputSpec("password",
@@ -78,15 +106,19 @@ private DialogWindowSpec createLoginDialogSpec(Function<MessageKey, String> text
             textResolver.apply(MessageKey.DIALOG_LOGIN_BUTTON),
             textResolver.apply(MessageKey.DIALOG_CANCEL_BUTTON),
             showSecondaryButton,
-            canCloseWithEscape);
+            canCloseWithEscape,
+            null,
+            showBody ? textResolver.apply(MessageKey.DIALOG_LOGIN_BODY) : null);
     }
 
     private DialogWindowSpec createRegisterDialogSpec(RegistrationType type,
                                                       RegisterSecondaryArgument secondArg,
                                                       Function<MessageKey, String> textResolver,
                                                       boolean showSecondaryButton,
                                                       boolean canCloseWithEscape) {
+        boolean showBody = commonService.getProperty(RegistrationSettings.DIALOG_SHOW_BODY);
         List<DialogInputSpec> inputs = new ArrayList<>();
+
         if (type == RegistrationType.EMAIL) {
             inputs.add(new DialogInputSpec("email",
                 textResolver.apply(MessageKey.DIALOG_REGISTER_EMAIL),
@@ -97,15 +129,21 @@ private DialogWindowSpec createRegisterDialogSpec(RegistrationType type,
                     DEFAULT_MAX_INPUT_LENGTH));
             }
         } else {
+            // For EMAIL_MANDATORY: email is placed before password — it is the account identifier
+            // and mirrors the signup order most players expect (email → then choose a password).
+            if (secondArg == RegisterSecondaryArgument.EMAIL_MANDATORY) {
+                inputs.add(new DialogInputSpec("email",
+                    textResolver.apply(MessageKey.DIALOG_REGISTER_EMAIL),
+                    DEFAULT_MAX_INPUT_LENGTH));
+            }
             inputs.add(new DialogInputSpec("password",
                 textResolver.apply(MessageKey.DIALOG_REGISTER_PASSWORD),
                 DEFAULT_MAX_INPUT_LENGTH));
             if (secondArg == RegisterSecondaryArgument.CONFIRMATION) {
                 inputs.add(new DialogInputSpec("confirm",
                     textResolver.apply(MessageKey.DIALOG_REGISTER_CONFIRM_PASSWORD),
                     DEFAULT_MAX_INPUT_LENGTH));
-            } else if (secondArg == RegisterSecondaryArgument.EMAIL_MANDATORY
-                || secondArg == RegisterSecondaryArgument.EMAIL_OPTIONAL) {
+            } else if (secondArg == RegisterSecondaryArgument.EMAIL_OPTIONAL) {
                 inputs.add(new DialogInputSpec("email",
                     textResolver.apply(MessageKey.DIALOG_REGISTER_EMAIL),
                     DEFAULT_MAX_INPUT_LENGTH));
@@ -118,7 +156,9 @@ private DialogWindowSpec createRegisterDialogSpec(RegistrationType type,
             textResolver.apply(MessageKey.DIALOG_REGISTER_BUTTON),
             textResolver.apply(MessageKey.DIALOG_CANCEL_BUTTON),
             showSecondaryButton,
-            canCloseWithEscape);
+            canCloseWithEscape,
+            null,
+            showBody ? textResolver.apply(MessageKey.DIALOG_REGISTER_BODY) : null);
     }
 
     private String getPostJoinMessage(Player player, MessageKey key) {

authme-core/src/main/java/fr/xephi/authme/settings/properties/RegistrationSettings.java

@@ -140,6 +140,25 @@ public final class RegistrationSettings implements SettingsHolder {
     public static final Property<Boolean> PRE_JOIN_REGISTER_CANCEL_KICKS =
         newProperty("settings.registration.preJoinDialog.registerCancelKicks", false);
 
+    @Comment({
+        "Kick players who cancel the Paper/Folia pre-join login dialog.",
+        "When false, cancelling lets the player join in limbo to use /email recover."})
+    public static final Property<Boolean> PRE_JOIN_LOGIN_CANCEL_KICKS =
+        newProperty("settings.registration.preJoinDialog.loginCancelKicks", true);
+
+    @Comment({
+        "Show a 'Forgot Password?' button in the post-join login dialog.",
+        "When clicked, executes /email recover using the email entered in the recovery field.",
+        "Requires an email provider to be configured to be useful."})
+    public static final Property<Boolean> DIALOG_SHOW_FORGOT_PASSWORD_BUTTON =
+        newProperty("settings.registration.dialog.showForgotPasswordButton", true);
+
+    @Comment({
+        "Show a short description body in login, register, and two-factor dialogs.",
+        "The body text helps players understand what the dialog is asking them to do."})
+    public static final Property<Boolean> DIALOG_SHOW_BODY =
+        newProperty("settings.registration.dialog.showBody", true);
+
 
     private RegistrationSettings() {
     }

authme-core/src/main/resources/messages/messages_bg.yml

@@ -136,17 +136,22 @@ verification:
 dialog:
   login:
     title: '&6Вход'
+    body: '&7Моля, въведете паролата си, за да продължите.'
     password: '&fПарола'
+    recovery_email: '&fИмейл за възстановяване (незадължително)'
+    recovery_button: '&eЗабравена парола?'
     button: '&aВход'
   register:
     title: '&6Регистрация'
+    body: '&7Създайте акаунт, за да започнете да играете на сървъра.'
     password: '&fПарола'
     confirm_password: '&fПотвърди паролата'
     email: '&fИмейл'
     confirm_email: '&fПотвърди имейла'
     button: '&aРегистриране'
   two_factor:
     title: '&6Двуфакторна автентикация'
+    body: '&7Отворете приложението за удостоверяване и въведете 6-цифрения код.'
     code: '&f2FA код'
     button: '&aПотвърди'
   button:

authme-core/src/main/resources/messages/messages_br.yml

@@ -154,17 +154,22 @@ two_factor:
 dialog:
   login:
     title: '&6Login'
+    body: '&7Por favor, insira sua senha para continuar.'
     password: '&fSenha'
+    recovery_email: '&fE-mail de recuperação (opcional)'
+    recovery_button: '&eEsqueceu a senha?'
     button: '&aEntrar'
   register:
     title: '&6Registro'
+    body: '&7Crie uma conta para começar a jogar neste servidor.'
     password: '&fSenha'
     confirm_password: '&fConfirmar senha'
     email: '&fE-mail'
     confirm_email: '&fConfirmar e-mail'
     button: '&aRegistrar'
   two_factor:
     title: '&6Autenticação de dois fatores'
+    body: '&7Abra seu aplicativo de autenticação e insira o código de 6 dígitos.'
     code: '&fCódigo 2FA'
     button: '&aVerificar'
   button:

authme-core/src/main/resources/messages/messages_cz.yml

@@ -138,17 +138,22 @@ verification:
 dialog:
   login:
     title: '&6Přihlášení'
+    body: '&7Pro pokračování zadejte své heslo.'
     password: '&fHeslo'
+    recovery_email: '&fObnovovací e-mail (volitelné)'
+    recovery_button: '&eZapomenuté heslo?'
     button: '&aPřihlásit se'
   register:
     title: '&6Registrace'
+    body: '&7Vytvořte si účet a začněte hrát na tomto serveru.'
     password: '&fHeslo'
     confirm_password: '&fPotvrdit heslo'
     email: '&fE-mail'
     confirm_email: '&fPotvrdit e-mail'
     button: '&aRegistrovat'
   two_factor:
     title: '&6Dvoufaktorové ověření'
+    body: '&7Otevřete svou autentizační aplikaci a zadejte 6místný kód.'
     code: '&fKód 2FA'
     button: '&aOvěřit'
   button:

authme-core/src/main/resources/messages/messages_de.yml

@@ -138,17 +138,22 @@ verification:
 dialog:
   login:
     title: '&6Anmeldung'
+    body: '&7Bitte gib dein Passwort ein, um fortzufahren.'
     password: '&fPasswort'
+    recovery_email: '&fWiederherstellungs-E-Mail (optional)'
+    recovery_button: '&ePasswort vergessen?'
     button: '&aAnmelden'
   register:
     title: '&6Registrierung'
+    body: '&7Erstelle ein Konto, um auf diesem Server zu spielen.'
     password: '&fPasswort'
     confirm_password: '&fPasswort bestätigen'
     email: '&fE-Mail'
     confirm_email: '&fE-Mail bestätigen'
     button: '&aRegistrieren'
   two_factor:
     title: '&6Zwei-Faktor-Authentifizierung'
+    body: '&7Öffne deine Authentifizierungs-App und gib den 6-stelligen Code ein.'
     code: '&f2FA-Code'
     button: '&aVerifizieren'
   button:

authme-core/src/main/resources/messages/messages_en.yml

@@ -148,17 +148,22 @@ two_factor:
 dialog:
   login:
     title: '&6Login'
+    body: '&7Please enter your password to continue.'
     password: '&fPassword'
+    recovery_email: '&fRecovery Email (optional)'
+    recovery_button: '&eForgot Password?'
     button: '&aLogin'
   register:
     title: '&6Register'
+    body: '&7Create an account to start playing on this server.'
     password: '&fPassword'
     confirm_password: '&fConfirm Password'
     email: '&fEmail'
     confirm_email: '&fConfirm Email'
     button: '&aRegister'
   two_factor:
     title: '&6Two-Factor Authentication'
+    body: '&7Open your authenticator app and enter the 6-digit code.'
     code: '&f2FA Code'
     button: '&aVerify'
   button:

authme-core/src/main/resources/messages/messages_eo.yml

@@ -138,17 +138,22 @@ verification:
 dialog:
   login:
     title: '&6Ensaluti'
+    body: '&7Bonvolu enigi vian pasvorton por daŭrigi.'
     password: '&fPasvorto'
+    recovery_email: '&fRetpoŝto por restarigo (nedeviga)'
+    recovery_button: '&eForgesita pasvorto?'
     button: '&aEnsaluti'
   register:
     title: '&6Registriĝo'
+    body: '&7Kreu konton por komenci ludi sur ĉi tiu servilo.'
     password: '&fPasvorto'
     confirm_password: '&fKonfirmi pasvorton'
     email: '&fRetpoŝto'
     confirm_email: '&fKonfirmi retpoŝton'
     button: '&aRegistriĝi'
   two_factor:
     title: '&6Du-ŝtupa aŭtentigo'
+    body: '&7Malfermu vian aŭtentikigan aplikaĵon kaj enigu la 6-cifran kodon.'
     code: '&f2FA-kodo'
     button: '&aKonfirmi'
   button: