v_chat_sdk 2.0.0-rc.3

V Chat Flutter SDK umbrella with client integration and accessible UI components.

v_chat_sdk

The public umbrella package for the V Chat Flutter SDK. Its primary library exports the Flutter SDK integration and the optional accessible, localized, themeable widget library from one dependency.

Release candidate 2.0.0-rc.3 supports Flutter >=3.38.0 and Dart >=3.10.0-0 <4.0.0. It is a breaking successor to the legacy v_chat_sdk 1.x package. Read MIGRATION.md before upgrading. The widget implementation remains presentation-only: it owns no client session, network request, database, authorization decision, retry, navigation, or state-management framework.

Installation

flutter pub add v_chat_sdk

Import the complete SDK and UI surface from the primary library:

import 'package:v_chat_sdk/v_chat_sdk.dart';

Client applications use only short-lived app-user tokens obtained from their own authenticated backend. Never embed a V Chat application credential, dashboard session secret, or signing key in a Flutter build. Compose one VChatFlutterSdk per signed-in user, call connectUser, and await dispose() during logout or profile switching. The complete lifecycle, REST, realtime, persistence, push, cancellation, and error examples are documented by v_chat_flutter.

Add localization and theme

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:v_chat_sdk/v_chat_sdk.dart';

final colorScheme = ColorScheme.fromSeed(seedColor: Colors.indigo);

MaterialApp(
  supportedLocales: VChatUiLocalizations.supportedLocales,
  localizationsDelegates: const <LocalizationsDelegate<dynamic>>[
    VChatUiLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  theme: ThemeData(
    colorScheme: colorScheme,
    extensions: <ThemeExtension<dynamic>>[
      VChatUiThemeData.fromColorScheme(colorScheme),
    ],
  ),
  home: const ChatScreen(),
);

English and Arabic are included. Flutter's localization delegates supply text direction and the Material/Cupertino strings needed for correct RTL behavior. VChatUiThemeData.fromColorScheme provides complete defaults; use copyWith when your design system needs selected colors, spacing, bubble radius, breakpoint, or pane width overrides.

Map SDK state into UI models

The widgets accept deliberately small, immutable presentation models. The host chooses safe display labels and timestamp formatting:

final rows = conversationSnapshots.map(
  (snapshot) => VChatUiConversation.fromSnapshot(
    snapshot,
    title: resolveConversationTitle(snapshot),
    preview: resolveConversationPreview(snapshot),
    timestampLabel: formatConversationTime(snapshot),
  ),
).toList(growable: false);

final messages = messageSnapshots.map(
  (snapshot) => VChatUiMessage.fromSnapshot(
    snapshot,
    currentUserId: currentUserId,
    authorLabel: resolveAuthorLabel(snapshot),
    timestampLabel: formatMessageTime(snapshot),
  ),
).toList(growable: false);

fromSnapshot copies only released display state and does not retain custom payloads. Use the direct constructors when presenting a host-owned optimistic row; select pending, failed, or sent delivery status explicitly and reconcile it with the server result.

Build a responsive chat screen

VChatAdaptiveChatLayout(
  showDetailOnCompact: selectedConversationId != null,
  conversationsPane: VChatConversationListView(
    items: rows,
    selectedConversationId: selectedConversationId,
    isLoadingMore: isLoadingMoreConversations,
    onLoadMore: loadMoreConversations,
    onConversationPressed: selectConversation,
  ),
  detailPane: Column(
    children: <Widget>[
      VChatConnectionStatusBanner(
        status: connectionStatus,
        actionLabel: canRetry ? 'Retry' : null,
        onAction: canRetry ? retryRealtime : null,
      ),
      Expanded(
        child: VChatMessageListView(
          messages: messages,
          isLoadingOlder: isLoadingOlderMessages,
          onLoadOlder: loadOlderMessages,
          onReact: reactToMessage,
          onOpenReplies: openReplies,
          onRetry: retryFailedMessage,
        ),
      ),
      VChatTypingIndicator(
        userLabels: visibleTypingUserLabels,
        totalCount: typingUserCount,
        truncated: typingUserCount > visibleTypingUserLabels.length,
      ),
      VChatMessageComposer(
        controller: composerController,
        enabled: canSend,
        isSending: isSending,
        clearOnSend: false,
        onSend: sendMessage,
      ),
    ],
  ),
);

Pass messages oldest-to-newest; the list keeps the newest row at the bottom. Pagination is always explicit through onLoadMore and onLoadOlder—scrolling does not silently perform network work. The host owns compact navigation by changing showDetailOnCompact.

Keep clearOnSend: false for asynchronous sends. Await the SDK mutation in host state, then clear the host-owned TextEditingController only after the message is accepted or intentionally converted to an optimistic row. This prevents text loss after a validation, authorization, or transport failure.

Widget reference

Widget/model	Purpose	Host responsibility
VChatAdaptiveChatLayout	Compact or two-pane master/detail layout	Selection and navigation
VChatConversationListView	Lazy keyed conversation rows and load-more control	Ordering, cursor, loading state
VChatConversationTile	One conversation row	Safe labels and selection callback
VChatMessageListView	Lazy chronological message list	Paging, mutations, optimistic state
VChatMessageBubble	One accessible message/tombstone	Retry, reaction, and reply actions
VChatMessageComposer	Controlled, bounded text submission	Async send and controller lifecycle
VChatTypingIndicator	Ephemeral bounded typing label	Map subscription activity to safe names
VChatConnectionStatusBanner	Accessible connection/recovery state	Map SDK state and choose explicit action
VChatEmptyState	Reusable empty/error placeholder	Optional action and product copy
VChatUiConversation	Display-safe conversation projection	Title, preview, timestamp, optimistic policy
VChatUiMessage	Display-safe message projection	Author label, timestamp, delivery status

Applications that only want presentation types may import the secondary library:

import 'package:v_chat_sdk/v_chat_flutter_ui.dart';

State ownership and safety

The host application owns:

• VChatFlutterSdk, login/logout, app-user token retrieval, and exact user switching;
• conversation/message streams, pagination cursors, loading/error state, and reconciliation;
• channel selection, routing, dialogs, attachment pickers, and reply screens;
• optimistic message IDs, retry decisions, moderation actions, and permission checks; and
• push permissions, native notifications, analytics, and product-specific accessibility testing.

The widgets do not infer authorization from cached rows and do not sanitize unsafe product strings for you. Supply labels intended for display, avoid secrets/private URLs, and do not place arbitrary server error messages into semantics or visible UI.

Dispose every controller, focus node, and SDK stream subscription that your host creates. These widgets dispose only objects they allocate internally.

Accessibility and RTL

Lists use stable keys and semantic child counts. Message, unread, typing, retry, and connection states have localized semantic labels. Test large text scale, keyboard navigation, screen readers, contrast, narrow layouts, and both English and Arabic in the real application; package widget tests cannot validate the full host navigation or product copy.

Support and security

Read the repository support, security, and privacy policies before production adoption. This is a release candidate; pin the exact version and review the changelog before upgrading.