@droppii-org/chat-mobile 0.2.81 → 0.2.82

package/src/screens/chat-detail/components/ChatMessageInput.tsx

@@ -5,8 +5,11 @@ import {
   TextInput,
   type NativeSyntheticEvent,
   type TextInputContentSizeChangeEventData,
+  type TextInputSelectionChangeEventData,
 } from 'react-native';
 import { KContainer, KImage, KColors, KSpacingValue } from '@droppii/libs';
+import { MentionHighlightAdapter } from './MentionHighlightAdapter';
+import type { Mention } from '../../../types/mention';
 
 const INPUT_FONT_SIZE = 16;
 const INPUT_LINE_HEIGHT = 22.4;
@@ -22,6 +25,15 @@ export interface ChatMessageInputProps {
   onContentSizeChange: (
     event: NativeSyntheticEvent<TextInputContentSizeChangeEventData>
   ) => void;
+  onSelectionChange?: (
+    event: NativeSyntheticEvent<TextInputSelectionChangeEventData>
+  ) => void;
+  /** Committed mentions — when non-empty, the input switches from plain
+   * `value` to a nested-Text `children` tree (MentionHighlightAdapter) so
+   * mentions render highlighted. Omitted/empty keeps the original plain
+   * `value`-controlled path, so the overwhelming majority of messages (no
+   * mentions) never pay for this. */
+  mentions?: Mention[];
   isInputFocused: boolean;
   isMultilineInput: boolean;
   onEmojiPress?: () => void;
@@ -37,12 +49,24 @@ export const ChatMessageInput = memo(
     onFocus,
     onBlur,
     onContentSizeChange,
+    onSelectionChange,
+    mentions,
     isInputFocused,
     isMultilineInput,
     onEmojiPress,
     onSuggestPress,
     inputRef,
   }: ChatMessageInputProps) => {
+    // Re-enabled: the earlier flicker/"Maximum update depth exceeded" loop
+    // was root-caused to two bugs in the composer wiring (unstable callback
+    // deps on `mentionComposer` recreating ChatMessageInput's onEmojiPress
+    // every render, and redundant/stale mention re-detection from
+    // onSelectionChange) — not the nested-Text children-mode rendering
+    // itself, which was disabled here as a precaution while that was still
+    // unclear. Both root causes are fixed in useMentionComposer.ts /
+    // ChatComposer.tsx. If a highlight-specific issue turns up on device,
+    // set this back to `false` — it's a one-line, fully reversible gate.
+    const hasMentions = !!mentions && mentions.length > 0;
     const renderEmojiNode = useCallback(
       () => (
         <KContainer.Touchable marginR="0.5rem" onPress={onEmojiPress}>
@@ -85,20 +109,29 @@ export const ChatMessageInput = memo(
             ref={inputRef}
             placeholder={placeholder}
             placeholderTextColor={KColors.palette.gray.w200}
-            value={value}
+            {...(hasMentions ? {} : { value })}
             onChangeText={onChangeText}
             onFocus={onFocus}
             onBlur={onBlur}
             onContentSizeChange={onContentSizeChange}
+            onSelectionChange={onSelectionChange}
             multiline
             blurOnSubmit={false}
+            autoCorrect={false}
             scrollEnabled
             allowFontScaling={false}
             underlineColorAndroid={KColors.transparent}
             selectionColor={KColors.selector}
             textAlignVertical={isMultilineInput ? 'top' : 'center'}
             style={[styles.textInput]}
-          />
+          >
+            {hasMentions && (
+              <MentionHighlightAdapter
+                text={value ?? ''}
+                mentions={mentions!}
+              />
+            )}
+          </TextInput>
 
           {renderEmojiNode()}
         </KContainer.View>

package/src/screens/chat-detail/components/MentionHighlightAdapter.tsx

@@ -0,0 +1,57 @@
+import { memo, useMemo } from 'react';
+import { Text } from 'react-native';
+import { KColors } from '@droppii/libs';
+import { tokenize } from '../../../utils/mentions';
+import type { Mention } from '../../../types/mention';
+
+interface MentionHighlightAdapterProps {
+  text: string;
+  mentions: Mention[];
+}
+
+/**
+ * Renders `text` as nested styled `<Text>` children for a TextInput's
+ * "undocumented" rich-text-via-children capability — the same primitive
+ * `react-native-controlled-mentions` and Bluesky's social-app both use.
+ *
+ * Deliberately STATELESS: every render calls tokenize() fresh and rebuilds
+ * the whole children tree from scratch — no attempt to preserve/diff span
+ * identity across renders. This is the Bluesky-informed choice (see the
+ * mention plan's Phase A3): react-native-controlled-mentions instead tries
+ * to maintain *stateful* span identity across renders, and its known
+ * Android bugs (#34668 duplicate input, #41647 broken selection, #50731
+ * "spans recreated on every render") read like that statefulness fighting
+ * itself — Bluesky ships live-colored nested-Text in production by never
+ * attempting to preserve identity in the first place. Only tokenize()
+ * itself is memoized (on [text, mentions]); the resulting element tree is
+ * not further diffed or cached.
+ *
+ * Only mounted when mentions.length > 0 (see ChatMessageInput) — a plain
+ * `value`-controlled TextInput is used otherwise, so the vast majority of
+ * messages (no mentions) never pay for this at all.
+ */
+export const MentionHighlightAdapter = memo(
+  ({ text, mentions }: MentionHighlightAdapterProps) => {
+    const segments = useMemo(() => tokenize(text, mentions), [text, mentions]);
+
+    return (
+      <>
+        {segments.map((segment, index) =>
+          segment.type === 'mention' ? (
+            <Text key={segment.mention.id} style={mentionTextStyle}>
+              {`@${segment.mention.displayName}`}
+            </Text>
+          ) : (
+            // Plain-text runs have no stable identity of their own — index
+            // is fine for a tree rebuilt from scratch every render.
+            <Text key={`text-${index}`}>{segment.text}</Text>
+          )
+        )}
+      </>
+    );
+  }
+);
+
+MentionHighlightAdapter.displayName = 'MentionHighlightAdapter';
+
+const mentionTextStyle = { color: KColors.palette.primary.w400 };

package/src/screens/chat-detail/components/MentionSuggestionItem.tsx

@@ -0,0 +1,53 @@
+import { memo, useCallback } from 'react';
+import { KContainer, KLabel, KColors, KImage } from '@droppii/libs';
+import Avatar from '../../../components/Avatar/Avatar';
+import { trans } from '../../../translation';
+import type { MentionSuggestion } from '../../../types/mention';
+
+const ALL_MEMBERS_USER_ID = 'ALL';
+
+interface MentionSuggestionItemProps {
+  item: MentionSuggestion;
+  onPress: (item: MentionSuggestion) => void;
+}
+
+export const MentionSuggestionItem = memo(
+  ({ item, onPress }: MentionSuggestionItemProps) => {
+    const isAllOption = item.userId === ALL_MEMBERS_USER_ID;
+
+    const handlePress = useCallback(() => onPress(item), [onPress, item]);
+
+    return (
+      <KContainer.Touchable row alignItems onPress={handlePress}>
+        {isAllOption ? (
+          <KContainer.View width={40} height={40} center>
+            <KImage.VectorIcons
+              name="user-three-b"
+              size={24}
+              color={KColors.palette.gray.w900}
+            />
+          </KContainer.View>
+        ) : (
+          <Avatar source={item.avatar} fullName={item.displayName} size="nm" />
+        )}
+
+        <KContainer.View flex marginL="0.75rem">
+          <KLabel.Text typo="TextMdMedium" numberOfLines={1}>
+            {item.displayName}
+          </KLabel.Text>
+          {isAllOption && (
+            <KLabel.Text
+              typo="TextXsNormal"
+              color={KColors.palette.gray.w600}
+              numberOfLines={1}
+            >
+              {trans('group:tag_all_desc')}
+            </KLabel.Text>
+          )}
+        </KContainer.View>
+      </KContainer.Touchable>
+    );
+  }
+);
+
+MentionSuggestionItem.displayName = 'MentionSuggestionItem';

package/src/screens/chat-detail/components/MentionSuggestionList.tsx

@@ -0,0 +1,133 @@
+import { memo, useCallback } from 'react';
+import { ActivityIndicator, StyleSheet } from 'react-native';
+import { LegendList } from '@legendapp/list/react-native';
+import { KContainer, KLabel, KColors, KSpacingValue } from '@droppii/libs';
+import { MentionSuggestionItem } from './MentionSuggestionItem';
+import { trans } from '../../../translation';
+import type { MentionSuggestion } from '../../../types/mention';
+
+// Figma (node 15066-319156): regular rows are 40px (single line, avatar
+// height defines it), the "Tất cả" row is 45px (title + subtitle) — 40 is
+// used as the shared estimate since most rows are the single-line kind.
+const ROW_HEIGHT = 40;
+const ROW_GAP = 8;
+const MAX_VISIBLE_ROWS = 6;
+const MAX_PANEL_HEIGHT =
+  ROW_HEIGHT * MAX_VISIBLE_ROWS + ROW_GAP * (MAX_VISIBLE_ROWS - 1);
+
+interface MentionSuggestionListProps {
+  suggestions: MentionSuggestion[];
+  isSearching: boolean;
+  isLoadingMore?: boolean;
+  hasMore?: boolean;
+  onLoadMore?: () => void;
+  onSelect: (item: MentionSuggestion) => void;
+}
+
+export const MentionSuggestionList = memo(
+  ({
+    suggestions,
+    isSearching,
+    isLoadingMore,
+    hasMore,
+    onLoadMore,
+    onSelect,
+  }: MentionSuggestionListProps) => {
+    const renderItem = useCallback(
+      ({ item }: { item: MentionSuggestion }) => (
+        <MentionSuggestionItem item={item} onPress={onSelect} />
+      ),
+      [onSelect]
+    );
+
+    const keyExtractor = useCallback(
+      (item: MentionSuggestion) => item.userId,
+      []
+    );
+
+    const renderFooter = useCallback(() => {
+      if (!isLoadingMore) return null;
+      return (
+        <KContainer.View paddingV="0.5rem" center>
+          <ActivityIndicator color={KColors.palette.primary.w400} />
+        </KContainer.View>
+      );
+    }, [isLoadingMore]);
+
+    const renderSeparator = useCallback(
+      () => <KContainer.View style={styles.separator} />,
+      []
+    );
+
+    return (
+      <KContainer.View style={styles.shadowWrapper}>
+        <KContainer.View background={KColors.white} style={styles.container}>
+          <KLabel.Text
+            typo="TextNmBold"
+            color={KColors.palette.gray.w600}
+            paddingH="0.75rem"
+            paddingV="0.5rem"
+          >
+            {trans('group:tag_title')}
+          </KLabel.Text>
+
+          {suggestions.length === 0 && !isSearching ? (
+            <KLabel.Text
+              typo="TextSmNormal"
+              color={KColors.palette.gray.w600}
+              paddingH="0.75rem"
+              paddingB="0.75rem"
+            >
+              {trans('group:tag_no_member_found')}
+            </KLabel.Text>
+          ) : suggestions.length === 0 && isSearching ? (
+            <KContainer.View paddingV="0.75rem" center>
+              <ActivityIndicator color={KColors.palette.primary.w400} />
+            </KContainer.View>
+          ) : (
+            <KContainer.View style={styles.listWrapper} padding="0.5rem">
+              <LegendList
+                data={suggestions}
+                renderItem={renderItem}
+                keyExtractor={keyExtractor}
+                estimatedItemSize={ROW_HEIGHT}
+                keyboardShouldPersistTaps="handled"
+                onEndReached={hasMore ? onLoadMore : undefined}
+                onEndReachedThreshold={0.5}
+                ListFooterComponent={renderFooter}
+                ItemSeparatorComponent={renderSeparator}
+              />
+            </KContainer.View>
+          )}
+        </KContainer.View>
+      </KContainer.View>
+    );
+  }
+);
+
+MentionSuggestionList.displayName = 'MentionSuggestionList';
+
+const styles = StyleSheet.create({
+  // Shadow lives on its own, non-clipping wrapper — a single view can't
+  // both clip to a rounded corner (overflow:'hidden', required below) and
+  // cast a shadow, since the clip cuts the shadow off too.
+  shadowWrapper: {
+    shadowColor: KColors.black,
+    shadowOffset: { width: 0, height: -8 },
+    shadowOpacity: 0.08,
+    shadowRadius: 16,
+    elevation: 4,
+  },
+  container: {
+    borderRadius: KSpacingValue['0.75rem'],
+    borderTopLeftRadius: KSpacingValue['0.75rem'],
+    borderTopRightRadius: KSpacingValue['0.75rem'],
+    overflow: 'hidden',
+  },
+  listWrapper: {
+    maxHeight: MAX_PANEL_HEIGHT,
+  },
+  separator: {
+    height: ROW_GAP,
+  },
+});

package/src/screens/chat-detail/hooks/useChatComposerState.ts

@@ -1,6 +1,12 @@
 import { useState, useMemo, useRef } from 'react';
 
-export type ActivePanelType = 'attachment' | 'sticker' | null;
+// 'mention' is used only for mutual-exclusion (closing attachment/sticker
+// when the mention picker opens) — the mention picker itself renders as its
+// own absolutely-positioned sibling in ChatComposer, not through this
+// state's render slot, since it must float above the input while the
+// keyboard stays open (attachment/sticker intentionally take over the
+// keyboard area, which the mention picker must not do).
+export type ActivePanelType = 'attachment' | 'sticker' | 'mention' | null;
 
 interface UseChatComposerStateReturn {
   activePanelType: ActivePanelType;

package/src/screens/chat-detail/hooks/useMentionComposer.ts

@@ -0,0 +1,344 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { TextInput, NativeSyntheticEvent } from 'react-native';
+import type { TextInputSelectionChangeEventData } from 'react-native';
+import { useInfiniteQuery } from '@tanstack/react-query';
+import debounce from 'lodash/debounce';
+import {
+  applyTextChange,
+  findActiveMention,
+  insertMention,
+} from '../../../utils/mentions';
+import { trans } from '../../../translation';
+import { mentionQueryKeys } from '../../../hooks/query-keys';
+import type {
+  ActiveMention,
+  Mention,
+  MentionSearchSource,
+  MentionSuggestion,
+} from '../../../types/mention';
+
+const SEARCH_DEBOUNCE_MS = 200;
+// Matches MentionSuggestionList's MAX_VISIBLE_ROWS — one page fills exactly
+// one screenful of the panel, so scrolling further triggers loadMore instead
+// of over-fetching members the user hasn't scrolled to yet.
+const SEARCH_LIMIT = 4;
+const ALL_MEMBERS_USER_ID = 'ALL';
+
+const allMembersSuggestion = (): MentionSuggestion => ({
+  userId: ALL_MEMBERS_USER_ID,
+  displayName: trans('group:tag_all'),
+});
+
+interface UseMentionComposerParams {
+  text: string;
+  setText: (text: string) => void;
+  searchSource: MentionSearchSource;
+  /** Namespaces the react-query cache per conversation — see the query
+   * itself for why this matters even though the hook is expected to remount
+   * per chat-detail screen. */
+  groupID?: string;
+  /** Mention only makes sense in group conversations (tagging a specific
+   * other member) — false for 1-1/bot/customer threads disables "@"
+   * detection entirely, not just the search results. Without this, typing
+   * "@" in a non-group chat would still open the picker (empty, since
+   * there's no real MentionSearchSource for it) instead of behaving as a
+   * plain character. Defaults to true so existing group-only callers don't
+   * need to pass it. */
+  enabled?: boolean;
+  inputRef: React.RefObject<TextInput | null>;
+}
+
+export interface UseMentionComposerReturn {
+  mentions: Mention[];
+  activeMention: ActiveMention | null;
+  suggestions: MentionSuggestion[];
+  isSearching: boolean;
+  isLoadingMore: boolean;
+  hasMore: boolean;
+  loadMore: () => void;
+  isPanelOpen: boolean;
+  handleChangeText: (text?: string) => void;
+  handleSelectionChange: (
+    event: NativeSyntheticEvent<TextInputSelectionChangeEventData>
+  ) => void;
+  selectSuggestion: (item: MentionSuggestion) => void;
+  closeMentionPanel: () => void;
+  clear: () => void;
+}
+
+/**
+ * Orchestrates the @mention composer: wires the pure Phase A1 logic
+ * (findActiveMention / applyTextChange / insertMention) and an injected
+ * MentionSearchSource into the live TextInput event loop.
+ *
+ * `text` stays owned by useChatCompose (the existing composer state) — this
+ * hook doesn't duplicate it, only mirrors it into a ref for synchronous
+ * access within its own event handlers (see textRef below).
+ */
+export function useMentionComposer({
+  text,
+  setText,
+  searchSource,
+  groupID,
+  enabled = true,
+  inputRef,
+}: UseMentionComposerParams): UseMentionComposerReturn {
+  const [mentions, setMentions] = useState<Mention[]>([]);
+  const [activeMention, setActiveMention] = useState<ActiveMention | null>(
+    null
+  );
+  // The keyword actually being searched for — distinct from
+  // activeMention.keyword, which updates on every keystroke. This only
+  // changes 200ms after typing pauses (see debouncedSetKeywordRef below),
+  // and IS the react-query key: typing further characters within the debounce
+  // window never touches the query at all, so the previous page's results
+  // stay on screen with zero flicker until the debounce actually fires.
+  // null means "no active search" (panel closed) — distinct from '' (an
+  // active search for the empty keyword, which also lists all members).
+  const [debouncedKeyword, setDebouncedKeyword] = useState<string | null>(null);
+
+  // Synchronous mirrors of the externally-owned `text` and internally-owned
+  // `mentions` state. React state updates aren't visible until the next
+  // render, but applyTextChange needs the *actual* latest committed values
+  // within the same tick a keystroke is processed — these refs are updated
+  // in lockstep with every setText/setMentions call below so they never lag.
+  const textRef = useRef(text);
+  const mentionsRef = useRef<Mention[]>([]);
+  const activeMentionRef = useRef<ActiveMention | null>(null);
+
+  const searchSourceRef = useRef(searchSource);
+  searchSourceRef.current = searchSource;
+
+  const enabledRef = useRef(enabled);
+  enabledRef.current = enabled;
+
+  useEffect(() => {
+    // External text changes not driven by this hook (e.g. clearing the
+    // composer after send) — keep the mirror and mention state in sync.
+    if (text !== textRef.current) {
+      textRef.current = text;
+      if (text === '') {
+        mentionsRef.current = [];
+        setMentions([]);
+      }
+    }
+  }, [text]);
+
+  const debouncedSetKeywordRef = useRef(
+    debounce(
+      (keyword: string) => setDebouncedKeyword(keyword),
+      SEARCH_DEBOUNCE_MS,
+      { leading: false, trailing: true }
+    )
+  );
+  useEffect(() => () => debouncedSetKeywordRef.current.cancel(), []);
+
+  const isActiveSearch = debouncedKeyword !== null;
+
+  const { data, isFetching, isFetchingNextPage, hasNextPage, fetchNextPage } =
+    useInfiniteQuery({
+      queryKey: mentionQueryKeys.search(groupID ?? '', debouncedKeyword ?? ''),
+      queryFn: ({ pageParam }) =>
+        searchSourceRef.current.search({
+          keyword: debouncedKeyword ?? '',
+          limit: SEARCH_LIMIT,
+          offset: pageParam,
+        }),
+      // Neither getGroupMemberList nor searchGroupMembers returns a total, so
+      // "is there a next page" is inferred from page size (see
+      // MentionSearchResult.hasMore's doc comment) instead of an exact count.
+      getNextPageParam: (lastPage, allPages) =>
+        lastPage.hasMore
+          ? allPages.reduce((sum, p) => sum + p.items.length, 0)
+          : undefined,
+      initialPageParam: 0,
+      enabled: isActiveSearch,
+      // Deliberately no maxPages cap — this is a scrolling picker, not a
+      // one-shot search; capping pages would drop already-loaded members as
+      // the user scrolls further, which is a worse experience than the memory
+      // cost of keeping them.
+    });
+
+  const includeAll = debouncedKeyword === '';
+  const suggestions = useMemo(() => {
+    const items = data?.pages.flatMap((page) => page.items) ?? [];
+    return includeAll ? [allMembersSuggestion(), ...items] : items;
+  }, [data, includeAll]);
+
+  const loadMore = useCallback(() => {
+    if (!isActiveSearch || !hasNextPage || isFetchingNextPage) return;
+    fetchNextPage();
+  }, [isActiveSearch, hasNextPage, isFetchingNextPage, fetchNextPage]);
+
+  const updateActiveMentionAndSearch = useCallback(
+    (currentText: string, cursor: number) => {
+      // Non-group conversation — "@" is a plain character, never a trigger.
+      // Checked here (not just left to the search source returning empty)
+      // so the picker UI never opens at all in this case.
+      const active = enabledRef.current
+        ? findActiveMention(currentText, cursor)
+        : null;
+      activeMentionRef.current = active;
+      setActiveMention(active);
+
+      if (!active) {
+        debouncedSetKeywordRef.current.cancel();
+        // Functional updater so an already-null value doesn't force a
+        // render on every ordinary keystroke (the common case).
+        setDebouncedKeyword((prev) => (prev === null ? prev : null));
+        return;
+      }
+
+      debouncedSetKeywordRef.current(active.keyword);
+    },
+    []
+  );
+
+  // Simplified from an earlier microtask-buffered design (see git history /
+  // plan doc for why that existed) after it caused a real, reproduced
+  // "Maximum update depth exceeded" loop in production testing. Root cause
+  // wasn't fully isolated without device logs, but the buffering added a
+  // second, redundant path (onSelectionChange re-running mention detection
+  // with native selection data that could be stale relative to the edit
+  // onChangeText had just processed) that could set state back and forth.
+  // applyTextChange already derives an authoritative cursor from the text
+  // diff itself — it never needed to wait for onSelectionChange for the
+  // edit case, so handling each event directly, synchronously, removes an
+  // entire dimension of timing uncertainty instead of trying to patch it.
+  const handleChangeText = useCallback(
+    (nextText?: string) => {
+      const nextTextRaw = nextText ?? '';
+      const previousText = textRef.current;
+      if (nextTextRaw === previousText) return;
+
+      const result = applyTextChange(
+        previousText,
+        mentionsRef.current,
+        nextTextRaw
+      );
+      textRef.current = result.text;
+      mentionsRef.current = result.mentions;
+      setText(result.text);
+      setMentions(result.mentions);
+
+      if (result.mentionRemoved) {
+        // The native buffer currently shows nextTextRaw, not our corrected
+        // result.text — force the cursor back to a position that's valid
+        // once React re-renders the controlled value.
+        requestAnimationFrame(() => {
+          inputRef.current?.setSelection(result.cursor, result.cursor);
+        });
+      }
+
+      updateActiveMentionAndSearch(result.text, result.cursor);
+    },
+    [inputRef, setText, updateActiveMentionAndSearch]
+  );
+
+  // Only meaningful for a pure cursor move with NO accompanying text change
+  // (tap elsewhere in the draft, arrow keys) — an edit's cursor is already
+  // handled authoritatively inside handleChangeText above. Deliberately
+  // does not re-run search/active-mention detection here to avoid the
+  // redundant double-handling that caused the loop this replaced.
+  const handleSelectionChange = useCallback(
+    (event: NativeSyntheticEvent<TextInputSelectionChangeEventData>) => {
+      const selection = event.nativeEvent.selection;
+      if (selection.start !== selection.end) return;
+      if (selection.start === textRef.current.length) return; // typical post-edit echo, already handled
+
+      updateActiveMentionAndSearch(textRef.current, selection.start);
+    },
+    [updateActiveMentionAndSearch]
+  );
+
+  const selectSuggestion = useCallback(
+    (item: MentionSuggestion) => {
+      const active = activeMentionRef.current;
+      if (!active) return;
+
+      const result = insertMention(
+        textRef.current,
+        mentionsRef.current,
+        active,
+        {
+          userId: item.userId,
+          displayName: item.displayName,
+        }
+      );
+
+      textRef.current = result.text;
+      mentionsRef.current = result.mentions;
+      setText(result.text);
+      setMentions(result.mentions);
+      activeMentionRef.current = null;
+      setActiveMention(null);
+      debouncedSetKeywordRef.current.cancel();
+      setDebouncedKeyword(null);
+
+      requestAnimationFrame(() => {
+        inputRef.current?.setSelection(result.cursor, result.cursor);
+      });
+    },
+    [inputRef, setText]
+  );
+
+  // Called by ChatComposer when the user explicitly opens the
+  // attachment/sticker panel while a mention query is active — the mutual
+  // exclusion works both directions: opening mention closes attachment/
+  // sticker (ChatComposer's own handlers already do that reactively, see
+  // the effect wired there), and this closes mention when the user
+  // deliberately switches to a different panel.
+  const closeMentionPanel = useCallback(() => {
+    activeMentionRef.current = null;
+    setActiveMention(null);
+    debouncedSetKeywordRef.current.cancel();
+    setDebouncedKeyword(null);
+  }, []);
+
+  // Defensive: if `enabled` ever flips false while a mention query happens
+  // to be open (e.g. conversation type resolves after mount), close it
+  // immediately rather than leaving a stale picker for a thread that
+  // shouldn't have one at all.
+  useEffect(() => {
+    if (!enabled) closeMentionPanel();
+    // closeMentionPanel is stable ([] deps) — listing it here doesn't cause
+    // extra runs, it just keeps the deps array honest instead of suppressing
+    // the lint rule.
+  }, [enabled, closeMentionPanel]);
+
+  // Called explicitly by ChatComposer right when it clears the composer
+  // after send. The existing `useEffect` watching the `text` prop *would*
+  // eventually sync mentions to [] once `compose.setText('')` propagates
+  // down as a new `text` prop — but that's a render later, and in between
+  // there's a real transient bug: `value` is already '' while `mentions`
+  // still holds the old (now-stale) entries, and tokenize('', oldMentions)
+  // happily emits a mention segment anchored past the end of an empty
+  // string — a "ghost" mention with no surrounding text. Clearing
+  // synchronously here, in the same tick as setText(''), removes that
+  // window entirely instead of just shrinking it.
+  const clear = useCallback(() => {
+    textRef.current = '';
+    mentionsRef.current = [];
+    activeMentionRef.current = null;
+    setMentions([]);
+    setActiveMention(null);
+    debouncedSetKeywordRef.current.cancel();
+    setDebouncedKeyword(null);
+  }, []);
+
+  return {
+    mentions,
+    activeMention,
+    suggestions,
+    isSearching: isActiveSearch && isFetching && !isFetchingNextPage,
+    isLoadingMore: isFetchingNextPage,
+    hasMore: !!hasNextPage,
+    loadMore,
+    isPanelOpen: activeMention !== null,
+    handleChangeText,
+    handleSelectionChange,
+    selectSuggestion,
+    closeMentionPanel,
+    clear,
+  };
+}