compose: Change topic input hint text

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

Author: PIG208

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.",

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:

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…';

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…';

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…';

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…';

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…';

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…';

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…';

lib/widgets/compose_box.dart

@@ -680,15 +680,104 @@ class _TopicInput extends StatefulWidget {
 }
 
 class _TopicInputState extends State<_TopicInput> {
+  void _topicFocusChanged() {
+    setState(() {
+      if (widget.controller.topicFocusNode.hasFocus) {
+        widget.controller.topicInteractionStatus.value =
+          ComposeTopicInteractionStatus.isEditing;
+      } else if (!widget.controller.contentFocusNode.hasFocus) {
+        widget.controller.topicInteractionStatus.value =
+          ComposeTopicInteractionStatus.notEditingNotChosen;
+      }
+    });
+  }
+
+  void _contentFocusChanged() {
+    setState(() {
+      if (widget.controller.contentFocusNode.hasFocus) {
+        widget.controller.topicInteractionStatus.value =
+          ComposeTopicInteractionStatus.hasChosen;
+      }
+    });
+  }
+
+  void _topicInteractionStatusChanged() {
+    setState(() {
+      // The actual state lives in widget.controller.topicInteractionStatus
+    });
+  }
+
+  @override
+  void initState() {
+    super.initState();
+    widget.controller.topicFocusNode.addListener(_topicFocusChanged);
+    widget.controller.contentFocusNode.addListener(_contentFocusChanged);
+    widget.controller.topicInteractionStatus.addListener(_topicInteractionStatusChanged);
+  }
+
+  @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.topicInteractionStatus.removeListener(_topicInteractionStatusChanged);
+      widget.controller.topicInteractionStatus.addListener(_topicInteractionStatusChanged);
+    }
+  }
+
+  @override
+  void dispose() {
+    widget.controller.topicFocusNode.removeListener(_topicFocusChanged);
+    widget.controller.contentFocusNode.removeListener(_contentFocusChanged);
+    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));
+    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.topicInteractionStatus.value,
+    )) {
+      (false, ComposeTopicInteractionStatus.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, ComposeTopicInteractionStatus.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, ComposeTopicInteractionStatus.notEditingNotChosen) ||
+      (true, _) => InputDecoration(
+        // Otherwise, show a short hint text for less distraction.
+        hintText: zulipLocalizations.composeBoxTopicHintText,
+        hintStyle: hintStyle),
+    };
 
     return TopicAutocomplete(
       streamId: widget.streamId,
@@ -705,10 +794,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)));
   }
 }
 
@@ -1381,17 +1467,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
+///    topic to content.
+/// ```
+///
+/// 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 inputs 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();
   }
 }

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>> {