compose: Change topic input hint text

PIG208 · PIG208 · commit b4344c723f16 · 2025-05-08T15:57:02.000-04:00
This is similar to web's behavior. When topics are not mandatory: - an alternative hint text "Enter a topic (skip for “general chat”)" is shown when the topic input has focus; - an opaque placeholder text (e.g.: "general chat") is shown if the user skipped to content input; Because the topic input is always shown in a message list page channel narrow (assuming permission to send messages), this also adds an initial state: - a short hint text, "Topic", is shown if the user hasn't interacted with topic or content inputs at all, or when the user unfocused topic input without moving focus to content input. This only changes the topic input's hint text. See CZO discussion for design details: https://chat.zulip.org/#narrow/channel/530-mobile-design/topic/general.20chat.20design.20.23F1297/near/2106736
diff --git a/assets/l10n/app_en.arb b/assets/l10n/app_en.arb
@@ -379,6 +379,13 @@
   "@composeBoxTopicHintText":  {
     "description": "Hint text for topic input widget in compose box."
   },
+  "composeBoxEnterTopicOrSkipHintText": "Enter a topic (skip for “{defaultTopicName}”)",
+  "@composeBoxEnterTopicOrSkipHintText":  {
+    "description": "Hint text for topic input widget in compose box when topics are optional.",
+    "placeholders": {
+      "defaultTopicName": {"type": "String", "example": "general chat"}
+    }
+  },
   "composeBoxUploadingFilename": "Uploading {filename}…",
   "@composeBoxUploadingFilename": {
     "description": "Placeholder in compose box showing the specified file is currently uploading.",
diff --git a/lib/generated/l10n/zulip_localizations.dart b/lib/generated/l10n/zulip_localizations.dart
@@ -622,6 +622,12 @@ abstract class ZulipLocalizations {
   /// **'Topic'**
   String get composeBoxTopicHintText;
 
+  /// Hint text for topic input widget in compose box when topics are optional.
+  ///
+  /// In en, this message translates to:
+  /// **'Enter a topic (skip for “{defaultTopicName}”)'**
+  String composeBoxEnterTopicOrSkipHintText(String defaultTopicName);
+
   /// Placeholder in compose box showing the specified file is currently uploading.
   ///
   /// In en, this message translates to:
diff --git a/lib/generated/l10n/zulip_localizations_ar.dart b/lib/generated/l10n/zulip_localizations_ar.dart
@@ -316,6 +316,11 @@ class ZulipLocalizationsAr extends ZulipLocalizations {
   @override
   String get composeBoxTopicHintText => 'Topic';
 
+  @override
+  String composeBoxEnterTopicOrSkipHintText(String defaultTopicName) {
+    return 'Enter a topic (skip for “$defaultTopicName”)';
+  }
+
   @override
   String composeBoxUploadingFilename(String filename) {
     return 'Uploading $filename…';
diff --git a/lib/generated/l10n/zulip_localizations_en.dart b/lib/generated/l10n/zulip_localizations_en.dart
@@ -316,6 +316,11 @@ class ZulipLocalizationsEn extends ZulipLocalizations {
   @override
   String get composeBoxTopicHintText => 'Topic';
 
+  @override
+  String composeBoxEnterTopicOrSkipHintText(String defaultTopicName) {
+    return 'Enter a topic (skip for “$defaultTopicName”)';
+  }
+
   @override
   String composeBoxUploadingFilename(String filename) {
     return 'Uploading $filename…';
diff --git a/lib/generated/l10n/zulip_localizations_ja.dart b/lib/generated/l10n/zulip_localizations_ja.dart
@@ -316,6 +316,11 @@ class ZulipLocalizationsJa extends ZulipLocalizations {
   @override
   String get composeBoxTopicHintText => 'Topic';
 
+  @override
+  String composeBoxEnterTopicOrSkipHintText(String defaultTopicName) {
+    return 'Enter a topic (skip for “$defaultTopicName”)';
+  }
+
   @override
   String composeBoxUploadingFilename(String filename) {
     return 'Uploading $filename…';
diff --git a/lib/generated/l10n/zulip_localizations_nb.dart b/lib/generated/l10n/zulip_localizations_nb.dart
@@ -316,6 +316,11 @@ class ZulipLocalizationsNb extends ZulipLocalizations {
   @override
   String get composeBoxTopicHintText => 'Topic';
 
+  @override
+  String composeBoxEnterTopicOrSkipHintText(String defaultTopicName) {
+    return 'Enter a topic (skip for “$defaultTopicName”)';
+  }
+
   @override
   String composeBoxUploadingFilename(String filename) {
     return 'Uploading $filename…';
diff --git a/lib/generated/l10n/zulip_localizations_pl.dart b/lib/generated/l10n/zulip_localizations_pl.dart
@@ -323,6 +323,11 @@ class ZulipLocalizationsPl extends ZulipLocalizations {
   @override
   String get composeBoxTopicHintText => 'Wątek';
 
+  @override
+  String composeBoxEnterTopicOrSkipHintText(String defaultTopicName) {
+    return 'Enter a topic (skip for “$defaultTopicName”)';
+  }
+
   @override
   String composeBoxUploadingFilename(String filename) {
     return 'Przekazywanie $filename…';
diff --git a/lib/generated/l10n/zulip_localizations_ru.dart b/lib/generated/l10n/zulip_localizations_ru.dart
@@ -324,6 +324,11 @@ class ZulipLocalizationsRu extends ZulipLocalizations {
   @override
   String get composeBoxTopicHintText => 'Тема';
 
+  @override
+  String composeBoxEnterTopicOrSkipHintText(String defaultTopicName) {
+    return 'Enter a topic (skip for “$defaultTopicName”)';
+  }
+
   @override
   String composeBoxUploadingFilename(String filename) {
     return 'Загрузка $filename…';
diff --git a/lib/generated/l10n/zulip_localizations_sk.dart b/lib/generated/l10n/zulip_localizations_sk.dart
@@ -316,6 +316,11 @@ class ZulipLocalizationsSk extends ZulipLocalizations {
   @override
   String get composeBoxTopicHintText => 'Topic';
 
+  @override
+  String composeBoxEnterTopicOrSkipHintText(String defaultTopicName) {
+    return 'Enter a topic (skip for “$defaultTopicName”)';
+  }
+
   @override
   String composeBoxUploadingFilename(String filename) {
     return 'Uploading $filename…';
diff --git a/lib/generated/l10n/zulip_localizations_uk.dart b/lib/generated/l10n/zulip_localizations_uk.dart
@@ -325,6 +325,11 @@ class ZulipLocalizationsUk extends ZulipLocalizations {
   @override
   String get composeBoxTopicHintText => 'Тема';
 
+  @override
+  String composeBoxEnterTopicOrSkipHintText(String defaultTopicName) {
+    return 'Enter a topic (skip for “$defaultTopicName”)';
+  }
+
   @override
   String composeBoxUploadingFilename(String filename) {
     return 'Завантаження $filename…';
diff --git a/lib/widgets/compose_box.dart b/lib/widgets/compose_box.dart
@@ -681,16 +681,115 @@ class _TopicInput extends StatefulWidget {
 }
 
 class _TopicInputState extends State<_TopicInput> {
+  void _topicOrContentFocusChanged() {
+    setState(() {
+      final status = widget.controller.topicInteractionStatus;
+      if (widget.controller.topicFocusNode.hasFocus) {
+        // topic input gains focus
+        status.value = ComposeTopicInteractionStatus.isEditing;
+      } else if (widget.controller.contentFocusNode.hasFocus) {
+        // content input gains focus
+        status.value = ComposeTopicInteractionStatus.hasChosen;
+      } else {
+        // neither input has focus, the new value of topicInteractionStatus
+        // depends on its previous value
+        if (status.value == ComposeTopicInteractionStatus.isEditing) {
+          // topic input loses focus
+          status.value = ComposeTopicInteractionStatus.notEditingNotChosen;
+        } else {
+          // content input loses focus; stay in hasChosen
+          assert(status.value == ComposeTopicInteractionStatus.hasChosen);
+        }
+      }
+    });
+  }
+
+  void _topicInteractionStatusChanged() {
+    setState(() {
+      // The actual state lives in widget.controller.topicInteractionStatus
+    });
+  }
+
+  @override
+  void initState() {
+    super.initState();
+    widget.controller.topicFocusNode.addListener(_topicOrContentFocusChanged);
+    widget.controller.contentFocusNode.addListener(_topicOrContentFocusChanged);
+    widget.controller.topicInteractionStatus.addListener(_topicInteractionStatusChanged);
+  }
+
+  @override
+  void didUpdateWidget(covariant _TopicInput oldWidget) {
+    super.didUpdateWidget(oldWidget);
+    if (oldWidget.controller != widget.controller) {
+      oldWidget.controller.topicFocusNode.removeListener(_topicOrContentFocusChanged);
+      widget.controller.topicFocusNode.addListener(_topicOrContentFocusChanged);
+      oldWidget.controller.contentFocusNode.removeListener(_topicOrContentFocusChanged);
+      widget.controller.contentFocusNode.addListener(_topicOrContentFocusChanged);
+      oldWidget.controller.topicInteractionStatus.removeListener(_topicInteractionStatusChanged);
+      widget.controller.topicInteractionStatus.addListener(_topicInteractionStatusChanged);
+    }
+  }
+
+  @override
+  void dispose() {
+    widget.controller.topicFocusNode.removeListener(_topicOrContentFocusChanged);
+    widget.controller.contentFocusNode.removeListener(_topicOrContentFocusChanged);
+    widget.controller.topicInteractionStatus.removeListener(_topicInteractionStatusChanged);
+    super.dispose();
+  }
+
   @override
   Widget build(BuildContext context) {
     final zulipLocalizations = ZulipLocalizations.of(context);
     final designVariables = DesignVariables.of(context);
-    TextStyle topicTextStyle = TextStyle(
+    final store = PerAccountStoreWidget.of(context);
+
+    final topicTextStyle = TextStyle(
       fontSize: 20,
       height: 22 / 20,
       color: designVariables.textInput.withFadedAlpha(0.9),
     ).merge(weightVariableTextStyle(context, wght: 600));
 
+    // TODO(server-10) simplify away
+    final emptyTopicsSupported = store.zulipFeatureLevel >= 334;
+
+    final String hintText;
+    TextStyle hintStyle = topicTextStyle.copyWith(
+      color: designVariables.textInput.withFadedAlpha(0.5));
+
+    if (store.realmMandatoryTopics) {
+      // Something short and not distracting.
+      hintText = zulipLocalizations.composeBoxTopicHintText;
+    } else {
+      switch (widget.controller.topicInteractionStatus.value) {
+        case ComposeTopicInteractionStatus.notEditingNotChosen:
+          // Something short and not distracting.
+          hintText = zulipLocalizations.composeBoxTopicHintText;
+        case ComposeTopicInteractionStatus.isEditing:
+          // The user is actively interacting with the input.  Since topics are
+          // not mandatory, show a long hint text mentioning that they can be
+          // left empty.
+          hintText = zulipLocalizations.composeBoxEnterTopicOrSkipHintText(
+            emptyTopicsSupported
+              ? store.realmEmptyTopicDisplayName
+              : kNoTopicTopic);
+        case ComposeTopicInteractionStatus.hasChosen:
+          // The topic has likely been chosen.  Since topics are not mandatory,
+          // show the default topic display name as if the user has entered that
+          // when they left the input empty.
+          if (emptyTopicsSupported) {
+            hintText = store.realmEmptyTopicDisplayName;
+            hintStyle = topicTextStyle.copyWith(fontStyle: FontStyle.italic);
+          } else {
+            hintText = kNoTopicTopic;
+            hintStyle = topicTextStyle;
+          }
+      }
+    }
+
+    final decoration = InputDecoration(hintText: hintText, hintStyle: hintStyle);
+
     return TopicAutocomplete(
       streamId: widget.streamId,
       controller: widget.controller.topic,
@@ -706,10 +805,7 @@ class _TopicInputState extends State<_TopicInput> {
           focusNode: widget.controller.topicFocusNode,
           textInputAction: TextInputAction.next,
           style: topicTextStyle,
-          decoration: InputDecoration(
-            hintText: zulipLocalizations.composeBoxTopicHintText,
-            hintStyle: topicTextStyle.copyWith(
-              color: designVariables.textInput.withFadedAlpha(0.5))))));
+          decoration: decoration)));
   }
 }
 
@@ -1382,17 +1478,67 @@ sealed class ComposeBoxController {
   }
 }
 
+/// Represent how a user has interacted with topic and content inputs.
+///
+/// State-transition diagram:
+///
+/// ```
+///                       (default)
+///    Topic input            │          Content input
+///    lost focus.            ▼          gained focus.
+///   ┌────────────► notEditingNotChosen ────────────┐
+///   │                                 │            │
+///   │         Topic input             │            │
+///   │         gained focus.           │            │
+///   │       ◄─────────────────────────┘            ▼
+/// isEditing ◄───────────────────────────── hasChosen
+///   │         Focus moved from             ▲ │     ▲
+///   │         content to topic.            │ │     │
+///   │                                      │ │     │
+///   └──────────────────────────────────────┘ └─────┘
+///    Focus moved from                        Content input loses focus
+///    topic to content.                       without topic input gaining it.
+/// ```
+///
+/// This state machine offers the following invariants:
+/// - When topic input has focus, the status must be [isEditing].
+/// - When content input has focus, the status must be [hasChosen].
+/// - When neither input has focus, and content input was the last
+///   input among the two to be focused, the status must be [hasChosen].
+/// - Otherwise, the status must be [notEditingNotChosen].
+enum ComposeTopicInteractionStatus {
+  /// The topic has likely not been chosen if left empty,
+  /// and is not being actively edited.
+  ///
+  /// When in this status neither the topic input nor the content input has focus.
+  notEditingNotChosen,
+
+  /// The topic is being actively edited.
+  ///
+  /// When in this status, the topic input must have focus.
+  isEditing,
+
+  /// The topic has likely been chosen, even if it is left empty.
+  ///
+  /// When in this status, the topic input must have no focus;
+  /// the content input might have focus.
+  hasChosen,
+}
+
 class StreamComposeBoxController extends ComposeBoxController {
   StreamComposeBoxController({required PerAccountStore store})
     : topic = ComposeTopicController(store: store);
 
   final ComposeTopicController topic;
   final topicFocusNode = FocusNode();
+  final ValueNotifier<ComposeTopicInteractionStatus> topicInteractionStatus =
+    ValueNotifier(ComposeTopicInteractionStatus.notEditingNotChosen);
 
   @override
   void dispose() {
     topic.dispose();
     topicFocusNode.dispose();
+    topicInteractionStatus.dispose();
     super.dispose();
   }
 }
diff --git a/test/flutter_checks.dart b/test/flutter_checks.dart
@@ -83,6 +83,7 @@ extension TextStyleChecks on Subject<TextStyle> {
   Subject<bool> get inherit => has((t) => t.inherit, 'inherit');
   Subject<Color?> get color => has((t) => t.color, 'color');
   Subject<double?> get fontSize => has((t) => t.fontSize, 'fontSize');
+  Subject<FontStyle?> get fontStyle => has((t) => t.fontStyle, 'fontStyle');
   Subject<FontWeight?> get fontWeight => has((t) => t.fontWeight, 'fontWeight');
   Subject<double?> get letterSpacing => has((t) => t.letterSpacing, 'letterSpacing');
   Subject<List<FontVariation>?> get fontVariations => has((t) => t.fontVariations, 'fontVariations');
@@ -228,6 +229,7 @@ extension ThemeDataChecks on Subject<ThemeData> {
 
 extension InputDecorationChecks on Subject<InputDecoration> {
   Subject<String?> get hintText => has((x) => x.hintText, 'hintText');
+  Subject<TextStyle?> get hintStyle => has((x) => x.hintStyle, 'hintStyle');
 }
 
 extension TextFieldChecks on Subject<TextField> {
diff --git a/test/widgets/compose_box_test.dart b/test/widgets/compose_box_test.dart
