fyral_comms 0.3.7

Communication feature package for Fleet Glide Admin

fyral_comms

A premium, responsive, and interactive messaging and team communication package for Flutter applications. Specifically tailored to handle both mobile and tablet interfaces seamlessly.

Features

• Top Broadcast Card (CommsPage): Dedicated Broadcast card at the top of the conversation list with unread counter badges, custom titles, timestamps, customizable megaphone/broadcast icons, and interactive tap handlers.
• Shimmer Skeleton Loading (ConversationShimmer): Smooth animated skeleton loader featuring linear gradient sweeps across message bubbles, avatars, and timestamps during initial conversation loading.
• WhatsApp-Style Date Separators (DateSeparatorBadge): Centered floating date pills automatically grouping messages by calendar date ("Today", "Yesterday", and formatted dates).
• Scroll-to-Top Pagination: Automatically triggers pagination callbacks (onLoadMoreMessages) when the user scrolls near the top of the chat history, with a sleek top loading indicator ("Loading earlier messages...").
• Fullscreen Interactive Media Viewer (FullscreenMediaViewer): Tapping any image or video attachment opens a dedicated fullscreen gallery view. Includes pinch-to-zoom and pan via InteractiveViewer, double-tap quick zoom toggle (1.0x <-> 2.5x), horizontal swipe page navigation (PageView) with dynamic gesture resolution when zoomed, and top toolbar counter (1 of N). Integrates full video playback controls (video_player) with tap-to-play gestures and format detection for network, file, and asset videos.
• BlurHash Placeholder Loading: Integrated flutter_blurhash to render smooth blurred image placeholders (BlurHash) during remote image network requests.
• Automatic Video Thumbnail Previews: MediaGrid renders video frame thumbnails automatically or uses explicit thumbnail URLs (thumbnail_url, thumbnail, poster) with translucent play button badges.
• WhatsApp-Style Media Preview (MediaPreviewPage): Interactive fullscreen preview for selected or captured photos and videos. Includes pinch-to-zoom support, video playback controls with live video frame thumbnails, horizontal swipe gestures (PageView), bottom thumbnail gallery strip, embedded Emoji Picker, and popup attachment actions.
• Dual-Source Attachment Picker: Clean popup menu on MessageBox supporting both Camera (ImagePicker) and Gallery (wechat_assets_picker / pickMultipleMedia) with Android 13+ / 14+ runtime permission handling and theme-adaptive upward popups.
• Responsive Dual-Pane Split-Screen: Automatically switches to a split-screen view on tablet-sized screens (width $\ge 600\text{px}$ in landscape, or $\ge 900\text{px}$ in portrait). Includes:
  • Left navigation sidebar panel showing active conversations.
  • Right viewport panel loading detail message logs.
• Integrated WhatsApp-style Replies: Reply card previews are nested cleanly inside the text input pill widget rather than covering the whole screen width, with rounded borders and color contrasts matching light/dark theme modes.
• Dynamic Mentions Suggestions Overlay: Typing @ displays a filtered user list overlay directly above the input container, presenting usernames and initials-based circular avatars.
• Rich-text Mentions Highlighting: Automatically colors active mentions in bold orange text both inside sent/received message bubbles and dynamically as you type inside the text input field.
• Dynamic Selection Highlighting: Sidebars highlight selected conversations with matching theme outline borders.
• Unified Gradient Headers: Left and right app bars share matching, beautiful steel-blue gradient backdrops.
• Morphing AI FAB Input Field: Circular Floating Action Button morphs into a full-width input query box at the bottom of the viewport with a fluid shape-morphing size and cross-fade animation.
• Adaptive Layout Adjustments: Conditionally suppresses screen navigation (like back arrows) in tablet views to prevent accidental page pops.
• Full Theme Support: Adapts typography, background colors, and borders automatically to match system light and dark themes.

Getting started

Add fyral_comms as a dependency in your pubspec.yaml file:

dependencies:
  fyral_comms: ^0.3.7

Or run:

flutter pub add fyral_comms

Platform & WeChat Asset Picker Setup

fyral_comms uses wechat_assets_picker for multi-media gallery picking with WeChat UI aesthetics, alongside image_picker for camera captures. To ensure smooth operation across Android and iOS, configure your host application with the required permissions and localizations:

1. Android Configuration (android/app/src/main/AndroidManifest.xml)

Add the following permissions to your AndroidManifest.xml:

<!-- Storage & Media Permissions -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

<!-- Camera Permission for photo captures -->
<uses-permission android:name="android.permission.CAMERA" />

Note: Ensure your android/app/build.gradle has compileSdkVersion set to 33 or higher.

2. iOS Configuration (ios/Runner/Info.plist)

Add the permission keys to your Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>Requires photo library access to pick photos and videos to share in conversations.</string>
<key>NSCameraUsageDescription</key>
<string>Requires camera access to capture photos and videos for messaging.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Requires microphone access to record videos with audio.</string>

3. Localization Setup (Recommended)

wechat_assets_picker relies on Flutter's localization system to render gallery UI labels (e.g. "Cancel", "Preview", "Send"). Add flutter_localizations to your pubspec.yaml and configure your MaterialApp:

dependencies:
  flutter_localizations:
    sdk: flutter

import 'package:flutter_localizations/flutter_localizations.dart';

MaterialApp(
  // ...
  localizationsDelegates: const [
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en', ''),
    // Add additional supported locales as needed
  ],
);

4. Automatic Fallback Mechanism

If photo library permissions are restricted or denied on Android/iOS, fyral_comms automatically falls back to system photo picker (image_picker / pickMultipleMedia()), ensuring an uninterrupted user experience.

Usage

Conversation List View (CommsPage)

Embed the CommsPage inside your application route configuration (e.g. using GoRouter) with optional Broadcast card support at the top of the list:

import 'package:fyral_comms/comms.dart';

CommsPage(
  currentUserId: 2,
  conversations: conversationGroups,
  onConversationSelected: (conversation) {
    context.push("/chat/${conversation.name}");
  },
  // Optional Broadcast Card at top of the conversation list:
  showBroadcast: true,
  broadcastTitle: 'Broadcast',
  broadcastMessage: 'Company-wide announcement: All routes updated',
  broadcastTime: '10:30 AM',
  broadcastUnreadCount: 2,
  onBroadcastTap: () {
    context.push("/chat/Broadcast");
  },
)

CommsPage Customization Options

• conversations (List<CommsGroup>?): List of active conversations/topics.
• onConversationSelected (Function(CommsGroup)?): Callback triggered when a conversation tile is tapped.
• showBroadcast (bool?, default: false): When true, displays a dedicated Broadcast card at index 0 at the top of the conversation list.
• broadcastTitle (String?, default: 'Broadcast'): Title displayed on the Broadcast card.
• broadcastMessage (String?, default: 'Broadcast messages & announcements'): Subtitle message content on the Broadcast card.
• broadcastTime (String?): Formatted time string displayed on the card.
• broadcastUnreadCount (int?, default: 0): Unread badge counter count.
• broadcastIcon (IconData?, default: Icons.campaign_rounded): Icon displayed inside the circular avatar.
• broadcastIconColor (Color?, default: Color(0xFFF97316)): Icon tint and avatar background accent color.
• onBroadcastTap (VoidCallback?): Tap callback handler for the Broadcast card.
• broadcastWidget (Widget?): Custom widget override for the Broadcast card.
• noDataIcon (IconData?): Custom icon when no conversations are found.
• emptyWidget (List<Widget>?): Custom widget list for the empty state.

Conversation Detail View

ConversationDetailPage provides a modular chat details view that supports a hybrid state management pattern.

Uncontrolled Mode (Stateful Fallback)

For quick prototyping, testing, or simple apps, you can instantiate the page with just a title. It will automatically initialize and manage its own messages list, text controllers, focus nodes, emoji pickers, and search states:

ConversationDetailPage(
  title: 'Operations Room',
)

Controlled Mode (Stateless Style)

For production applications, or when integrating with state management frameworks like BLoC, Riverpod, or Redux, you can fully drive the page externally by supplying controllers, state values, and event callbacks:

ConversationDetailPage(
  title: 'Operations Room',
  messages: state.messages,
  isSearching: state.isSearching,
  searchQuery: state.searchQuery,
  showEmojiPicker: state.showEmojiPicker,
  messageController: _messageController,
  searchController: _searchController,
  focusNode: _focusNode,
  onSendMessage: () => bloc.add(SendMessageEvent()),
  onSearchQueryChanged: (query) => bloc.add(SearchChangedEvent(query)),
  onToggleEmojiPicker: () => bloc.add(ToggleEmojiEvent()),
  onToggleSearch: () => bloc.add(ToggleSearchEvent()),
  onClearSearch: () => bloc.add(ClearSearchEvent()),
  onMediaPicked: (List<File> files) => bloc.add(MediaPickedEvent(files)),
  onBackPressed: () => Navigator.pop(context),
)

Customization Options

• isLoading (bool, default: false): Displays animated skeleton shimmer (ConversationShimmer) when messages are in initial loading state.
• isLoadingMore (bool, default: false): Displays a top loading indicator pill ("Loading earlier messages..." with progress spinner) while older history is being fetched.
• hasMoreMessages (bool, default: true): Indicates whether earlier messages exist for pagination.
• onLoadMoreMessages (Future<void> Function()?): Callback triggered automatically when user scrolls near the top of the chat.
• showDateSeparators (bool, default: true): Automatically groups messages by calendar day with floating WhatsApp-style date badges ("Today", "Yesterday", etc.).
• scrollController (ScrollController?): Optional external scroll controller.
• shimmerPlaceholder (Widget?): Custom shimmer placeholder widget override.
• emptyPlaceholder (Widget?): Custom empty state placeholder widget override when there are no messages.
• emptyTitle (String?, default: 'No messages yet'): Title text displayed in the empty state.
• emptySubtitle (String?, default: 'Send a message to start the conversation'): Subtitle informative message displayed in the empty state.
• emptyIcon (IconData?, default: Icons.chat_bubble_outline_rounded): Icon displayed inside the circular badge in the empty state.
• onMediaPicked (ValueChanged<List<File>>?): Callback invoked when media files are selected/captured and confirmed from the preview screen.
• showMediaPicker (bool?, default: true): Controls visibility of the attachment picker button in the message box.
• addDemoData (bool, default: true): If true, populates mock demo messages on initialization when in uncontrolled mode. Set to false to start with an empty chat log.
• showAppBar (bool, default: true): Set to false to hide the Scaffold's AppBar, allowing you to embed the page inside parent navigators or custom layouts.

Refer to the /example directory for a complete demonstration, including premium custom ThemeData configurations for both light and dark display modes.

Media Preview View (MediaPreviewPage)

You can launch MediaPreviewPage directly to preview picked photos and videos with captions before sending:

final MediaPreviewResult? result = await Navigator.push<MediaPreviewResult>(
  context,
  MaterialPageRoute(
    builder: (context) => MediaPreviewPage(
      filePaths: ['/path/to/image.png', '/path/to/video.mp4'],
      initialCaption: 'Check out the site photos',
    ),
  ),
);

if (result != null) {
  print('Selected files: ${result.filePaths}');
  print('Caption: ${result.caption}');
}

Conversation Card Tile (conversationCard)

The conversationCard widget renders a WhatsApp-style conversation list tile with responsive dark/light mode themes, unread badges, timestamps, and customizable avatars/icons:

conversationCard(
  title: 'Operations Group',
  message: 'Meeting starts at 10 AM',
  time: '9:45 AM',
  avatarIconColor: Colors.blueAccent,
  unreadCount: 3,
  isUnread: true,
  leadingIcon: Icons.groups_2_rounded,
  onTap: () => openConversation(),
);

Parameters:

• title (String, required): Title or group name.
• message (String, required): Last message preview text.
• time (String, required): Formatted timestamp.
• avatarIconColor (Color, required): Icon tint color.
• unreadCount (int, required): Unread message count.
• isUnread (bool, required): Highlights text and badges when true.
• isSelected (bool, default: false): Highlights card border and background for multi-pane split-screen views.
• leadingIcon (IconData, default: Icons.groups_2_rounded): Icon inside avatar.
• leadingWidget (Widget?): Replaces avatar with a custom widget.
• onTap (VoidCallback?): Tap event callback.

Additional information

• Repository: Find the source code and file issues on GitHub.
• Contributing: Feedback and pull requests are welcome. Feel free to file issues or request enhancements on the repository.