compose: Change topic input hint text

PIG208 · PIG208 · commit 513298058c6e · 2025-04-16T13:05:12.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 intial state: - a short hint text, "Topic", is shown if the user hasn't interacted with topic or content inputs at all. 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
@@ -609,6 +609,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
@@ -298,6 +298,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
@@ -298,6 +298,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
@@ -298,6 +298,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
@@ -298,6 +298,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
@@ -298,6 +298,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
@@ -298,6 +298,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
@@ -298,6 +298,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/widgets/compose_box.dart b/lib/widgets/compose_box.dart
@@ -682,15 +682,101 @@ class _TopicInput extends StatefulWidget {
 }
 
 class _TopicInputState extends State<_TopicInput> {
+  void _topicFocusChanged() {
+    setState(() {
+      if (widget.controller.topicFocusNode.hasFocus) {
+        widget.controller.topicEditStatus.value = ComposeTopicEditStatus.isEditing;
+      } else if (!widget.controller.contentFocusNode.hasFocus) {
+        widget.controller.topicEditStatus.value = ComposeTopicEditStatus.none;
+      }
+    });
+  }
+
+  void _contentFocusChanged() {
+    setState(() {
+      if (widget.controller.contentFocusNode.hasFocus) {
+        widget.controller.topicEditStatus.value = ComposeTopicEditStatus.hasChosen;
+      }
+    });
+  }
+
+  void _topicEditStatusChanged() {
+    setState(() {
+      // The actual state lives in widget.controller.topicEditStatus
+    });
+  }
+
+  @override
+  void initState() {
+    super.initState();
+    widget.controller.topicFocusNode.addListener(_topicFocusChanged);
+    widget.controller.contentFocusNode.addListener(_contentFocusChanged);
+    widget.controller.topicEditStatus.addListener(_topicEditStatusChanged);
+  }
+
+  @override
+  void didUpdateWidget(covariant _TopicInput oldWidget) {
+    super.didUpdateWidget(oldWidget);
+    if (oldWidget.controller != widget.controller) {
+      oldWidget.controller.topicFocusNode.removeListener(_topicFocusChanged);
+      widget.controller.topicFocusNode.addListener(_topicFocusChanged);
+      oldWidget.controller.contentFocusNode.removeListener(_contentFocusChanged);
+      widget.controller.contentFocusNode.addListener(_contentFocusChanged);
+      oldWidget.controller.topicEditStatus.removeListener(_topicEditStatusChanged);
+      widget.controller.topicEditStatus.addListener(_topicEditStatusChanged);
+    }
+  }
+
+  @override
+  void dispose() {
+    widget.controller.topicFocusNode.removeListener(_topicFocusChanged);
+    widget.controller.contentFocusNode.removeListener(_contentFocusChanged);
+    widget.controller.topicEditStatus.removeListener(_topicEditStatusChanged);
+    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));
+    final hintStyle = topicTextStyle.copyWith(
+      color: designVariables.textInput.withFadedAlpha(0.5));
+    final defaultTopicDisplayName = store.zulipFeatureLevel >= 334
+      ? store.realmEmptyTopicDisplayName : kNoTopicTopic;
+
+    final decoration = switch ((
+      store.realmMandatoryTopics,
+      widget.controller.topicEditStatus.value,
+    )) {
+      (false, ComposeTopicEditStatus.hasChosen) => InputDecoration(
+        // The topic has likely been chosen.  Since topics are not mandaotry,
+        // show the default topic display name as if the user has entered that
+        // when they left the input empty.
+        hintText: defaultTopicDisplayName,
+        hintStyle: topicTextStyle.copyWith(
+          fontStyle: store.zulipFeatureLevel >= 334 ? FontStyle.italic : null)),
+
+      (false, ComposeTopicEditStatus.isEditing) => InputDecoration(
+        // 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(
+          defaultTopicDisplayName),
+        hintStyle: hintStyle),
+
+      (false, ComposeTopicEditStatus.none) ||
+      (true, _) => InputDecoration(
+        // Otherwise, show a short hint text for less distraction.
+        hintText: zulipLocalizations.composeBoxTopicHintText,
+        hintStyle: hintStyle),
+    };
 
     return TopicAutocomplete(
       streamId: widget.streamId,
@@ -707,10 +793,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)));
   }
 }
 
@@ -1383,17 +1466,63 @@ sealed class ComposeBoxController {
   }
 }
 
+/// Represent how a user has edited the topic, by tracking their previous
+/// interactions with topic and content inputs.
+///
+/// State-transition diagram:
+///
+/// ```
+///        content input
+///        gains focus
+///   none ─────────────► hasChosen
+///    ▲    │                │  ▲
+///    │    └────────────────┤  │
+///    │      topic input    │  │ content input
+///    │      gains focus    │  │ gains focus
+///    │                     ▼  │
+///    └────────────────── isEditing
+///    topic input loses focus
+///    and content input has no focus
+/// ```
+///
+/// This state machine offers the following invariants:
+/// - When topic input has focus, the edit status must be [isEditing].
+/// - When content input has focus, the edit status must be [hasChosen].
+/// - Otherwise, the edit status can be either of [none] or [hasChosen],
+///   but never [isEditing].
+enum ComposeTopicEditStatus {
+  /// 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.
+  none,
+
+  /// 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,
+
+  /// The topic is being actively edited.
+  ///
+  /// When in this status, the topic input must have focus.
+  isEditing,
+}
+
 class StreamComposeBoxController extends ComposeBoxController {
   StreamComposeBoxController({required PerAccountStore store})
     : topic = ComposeTopicController(store: store);
 
   final ComposeTopicController topic;
   final topicFocusNode = FocusNode();
+  final ValueNotifier<ComposeTopicEditStatus> topicEditStatus =
+    ValueNotifier(ComposeTopicEditStatus.none);
 
   @override
   void dispose() {
     topic.dispose();
     topicFocusNode.dispose();
+    topicEditStatus.dispose();
     super.dispose();
   }
 }
diff --git a/test/flutter_checks.dart b/test/flutter_checks.dart
@@ -99,6 +99,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');
@@ -170,6 +171,7 @@ extension MaterialChecks on Subject<Material> {
 
 extension InputDecorationChecks on Subject<InputDecoration> {
   Subject<String?> get hintText => has((x) => x.hintText, 'hintText');
+  Subject<TextStyle?> get hintStyle => has((x) => x.hintStyle, 'hintStyle');
 }
 
 extension RadioListTileChecks<T> on Subject<RadioListTile<T>> {
diff --git a/test/widgets/compose_box_test.dart b/test/widgets/compose_box_test.dart
