@waysnx/ui-communication

🤖 AI agents & LLMs: See LLM.md (shipped with this package) for a structured integration guide — messaging, threads, presence, reactions, and collaboration hooks.

Enterprise-grade communication components for modern SaaS applications.

Provides reusable collaboration primitives — messaging, threads, presence, reactions, mentions, and realtime collaboration — without being opinionated about networking.

Installation

npm install @waysnx/ui-communication @waysnx/ui-core @waysnx/ui-layout @waysnx/ui-feedback

import '@waysnx/ui-communication/dist/index.css';
import '@waysnx/ui-core/dist/index.css';

Quick Start

import {
  CommunicationProvider,
  ConversationList,
  ChatWindow,
  useMessages,
} from '@waysnx/ui-communication';

function App() {
  return (
    <CommunicationProvider config={{ currentUser: { id: '1', name: 'You' } }}>
      <Chat />
    </CommunicationProvider>
  );
}

Components

| Component | Description | |-----------|-------------| | ConversationList | Searchable, filterable list of conversations | | ChatWindow | Complete chat view with messages, typing, and input | | MessageBubble | Message with variants: outgoing, incoming, system, AI | | ChatInput | Rich input with emoji, attachment, mention, voice buttons | | ThreadPanel | Threaded replies panel | | PresenceIndicator | Online/away/busy/offline status dot | | TypingIndicator | Animated typing dots with user names | | ReadReceipts | Sent/delivered/read status icons | | ReactionBar | Emoji reactions with counts | | EmojiPicker | Categorized emoji grid with search | | MentionInput | @mention autocomplete input | | VoiceMessage | Audio waveform player (playback only) | | UserPresenceList | Users list with presence status | | NotificationList | Notification feed with mark-as-read | | NotificationBadge | Unread count badge |

Design Philosophy

This library provides UI components only — it does not include networking, storage, or media capture logic. Your application is responsible for:

• Sending/receiving messages — use the RealtimeAdapter interface to connect to your backend
• File uploads — the 📎 button triggers onAttach; implement upload logic in your app
• Voice recording — the 🎤 button is a UI hook; use the browser MediaRecorder API and pass the audio blob as an attachment
• Voice playback — VoiceMessage is a player component; pass a pre-recorded audio URL via src
• Emoji insertion — EmojiPicker fires onSelect with the emoji character; your app inserts it into the message
• Mentions resolution — MentionInput provides UI autocomplete; your app supplies the user list and handles the mention data
• Presence & typing — the hooks emit events; your realtime adapter distributes them to other clients
• Notifications — NotificationList renders data you provide; your app fetches/manages notification state

This keeps the library lightweight, framework-agnostic on the backend, and compatible with any messaging infrastructure.

Hooks

| Hook | Description | |------|-------------| | useConversation() | Manage conversations (CRUD, pin, mute, archive) | | useMessages() | Send, edit, delete, react to messages | | useTyping() | Start/stop typing indicators | | usePresence() | Manage your own status and read others | | useMentions() | @mention search and selection | | useCommunication() | Access the full context from CommunicationProvider |

Realtime Adapters

No networking is hardcoded. Bring your own adapter:

import type { RealtimeAdapter } from '@waysnx/ui-communication';

const myAdapter: RealtimeAdapter = {
  connect: async (config) => { /* connect to your server */ },
  disconnect: async () => { /* cleanup */ },
  subscribe: (channel, callback) => { /* listen */ return () => {} },
  publish: async (channel, event) => { /* send */ },
  isConnected: () => true,
};

<CommunicationProvider config={{ currentUser, adapter: myAdapter, adapterConfig: { url: '...' } }}>
  <App />
</CommunicationProvider>

Supported adapters (bring your own implementation):

• WebSocket
• Laravel Reverb
• Socket.IO
• SignalR
• Firebase Realtime
• Supabase Realtime
• MQTT

Theming

All components use --wx-comm-* CSS custom properties that inherit from the base --wx-* tokens:

:root {
  --wx-comm-bubble-outgoing-bg: #2563eb;
  --wx-comm-bubble-incoming-bg: #f3f4f6;
  --wx-comm-presence-online: #22c55e;
  --wx-comm-presence-away: #f59e0b;
  --wx-comm-presence-busy: #ef4444;
}

Dark mode is automatic via [data-theme="dark"].

License

Apache-2.0 © WaysNX Technologies Private Limited