@pmate/chat-sdk 0.2.3 → 0.3.0

package/README.md

@@ -3,3 +3,32 @@
 Shared chat UI primitives, hooks, and state helpers used by PMate chat surfaces.
 
 This package contains the reusable chat input, attachment, emoji, and voice-related building blocks that PMate apps compose into product-specific chat experiences.
+
+## Group mentions
+
+### Background
+
+A host already knows its group membership. The SDK provides the same @ picker for
+built-in composers and custom textarea UIs without fetching business data.
+
+Pass `mentions={{ candidates: [{ id: profileId, name: displayName, avatar }] }}` to
+`ChatInputDesktop` or `ChatInputMobile`. Omit it in direct messages. Typing @ after
+whitespace or punctuation opens the member list; arrows navigate, Enter selects,
+Escape dismisses, and IME composition remains native. The next Enter sends.
+
+`onSend` includes `mentions?: ChatMention[]` with stable IDs and UTF-16 `[start, end)`
+ranges into the **untrimmed** `text`. Editing an inserted name removes its mention
+identity. Duplicate names retain distinct IDs. Pass mentions to `sendGroup` along
+with the ordinary group recipients; mention IDs must never replace recipients.
+This is selection metadata, not a push-notification or permission mechanism.
+
+For a custom textarea, call `useMentions({ value, onChange, config, disabled })`,
+spread its `inputProps`, render `<MentionMenu {...picker.menuProps} tokens={tokens} />`
+inside a relatively positioned wrapper, and send `picker.getMentions()` with value.
+If overriding `onKeyDown`, call `picker.inputProps.onKeyDown(event)` first and return
+when `event.defaultPrevented`. Hosts supply only valid current group candidates and
+must preserve the text offsets if transforming the message before transport.
+
+Storybook: `GroupMentions`, `MobileGroupMentions`, and `DarkGroupMentions` use the
+production components, include duplicate names and scrolling, and support empty
+results by typing an unmatched query.