spindle_chat 0.1.0

Composable, themeable chat UI for Flutter. Sealed message types, controller-driven state, InheritedWidget DI, animated list with date separators — no codegen, no heavy deps.

spindle_chat

Composable, themeable chat UI for Flutter.

---

Features

• Sealed message types — TextMessage, ImageMessage, FileMessage, SystemMessage, CustomMessage with exhaustive switch.
• Controller-driven — ChatController interface + InMemoryChatController with animated list operations (insert, remove, update, set).
• Theming — ChatTheme.light(), ChatTheme.dark(), or ChatTheme.fromThemeData(theme) to match your app.
• Custom builders — Override any widget via ChatBuilders (message bubble, avatar, input, system message, date separator, empty state).
• Localization — ChatL10n for translatable strings (input hint, empty state, date labels).
• Animated list — SliverAnimatedList with fade/slide transitions, date separators, and a scroll-to-bottom button.
• Accessibility — Semantics on bubbles, buttons, and system messages.
• Message groups — Consecutive messages from the same author are grouped visually.
• Delivery status — sent, delivered, seen, error indicators on outgoing messages.
• Edited indicator — Shows "edited" label when updatedAt != createdAt.
• Pagination — onLoadMore callback for lazy loading.
• Attachments — onAttachmentTap callback for photo/file picker integration.
• No codegen, no heavy deps — Only meta and intl.

---

Installation

dependencies:
  spindle_chat: ^0.1.0

flutter pub get

---

Quick start

import 'package:spindle_chat/spindle_chat.dart';

// 1. Create a controller
final controller = InMemoryChatController();

// 2. Add the ChatView
ChatView(
  controller: controller,
  currentUserId: 'user-123',
  resolveAuthor: (id) => ChatAuthor(
    id: id,
    displayName: 'User',
  ),
  onSend: (text) {
    controller.insertMessage(
      TextMessage(
        id: const Uuid().v4(),
        authorId: 'user-123',
        createdAt: DateTime.now(),
        text: text,
      ),
    );
  },
);

That's it. ChatView renders the message list, date separators, and the input bar.

---

Architecture

┌──────────────────────────────────────────┐
│                ChatView                  │
│  ┌─────────────────┐ ┌───────────────┐  │
│  │ ChatMessageList  │ │ ChatComposer  │  │
│  │ (SliverAnimated) │ │ (TextField)   │  │
│  └────────┬─────────┘ └──────┬────────┘  │
│           │                  │           │
│     ChatScope (InheritedWidget – DI)     │
│  ┌────────┴──────────────────┴────────┐  │
│  │  controller · theme · builders     │  │
│  │  resolveAuthor · l10n · callbacks  │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘
         │
   ChatController (interface)
         │
   InMemoryChatController
   ├─ messages: List<ChatMessage>
   ├─ insertMessage()
   ├─ removeMessage()
   ├─ updateMessage()
   └─ setMessages()

---

Message types

All message types are subtypes of the sealed class ChatMessage:

Type	Key fields
TextMessage	text
ImageMessage	imageUrl, width, height
FileMessage	fileName, fileUrl, mimeType, fileSizeBytes
SystemMessage	text
CustomMessage	metadata

Exhaustive matching with Dart 3 switch:

switch (message) {
  case TextMessage(:final text)       => Text(text),
  case ImageMessage(:final imageUrl)  => Image.network(imageUrl),
  case FileMessage(:final fileName)   => Text(fileName),
  case SystemMessage(:final text)     => Text(text, style: italicStyle),
  case CustomMessage(:final metadata) => CustomWidget(metadata),
}

---

Theming

From your app theme

ChatView(
  theme: ChatTheme.fromThemeData(Theme.of(context)),
  // ...
)

Custom colors

ChatView(
  theme: ChatTheme(
    colors: ChatColors(
      sentBubble: Colors.indigo,
      sentText: Colors.white,
      receivedBubble: Colors.grey.shade200,
      receivedText: Colors.black87,
      surface: Colors.white,
      onSurface: Colors.black,
      inputBackground: Colors.grey.shade100,
      inputText: Colors.black87,
      timestamp: Colors.grey,
      system: Colors.grey,
      divider: Colors.grey.shade300,
      seen: Colors.blue,
    ),
    typography: ChatTypography.standard(),
  ),
  // ...
)

---

Custom builders

Override any widget by passing a ChatBuilders:

ChatView(
  builders: ChatBuilders(
    textMessageBuilder: (context, message, isMine) =>
        MyCustomBubble(message),
    avatarBuilder: (context, author) =>
        CircleAvatar(child: Text(author.displayName[0])),
    dateSeparatorBuilder: (context, date) =>
        Center(child: Chip(label: Text(formatDate(date)))),
    emptyStateBuilder: (context) =>
        const Center(child: Text('Start chatting!')),
    systemMessageBuilder: (context, message) =>
        Text(message.text, style: TextStyle(color: Colors.grey)),
  ),
  // ...
)

---

Localization

ChatView(
  l10n: const ChatL10n(
    inputHint: 'Сообщение',
    emptyStateText: 'Нет сообщений',
    today: 'Сегодня',
    yesterday: 'Вчера',
  ),
  // ...
)

---

Message lifecycle

// Insert (triggers slide-in animation)
controller.insertMessage(message);

// Update (e.g. delivery status)
controller.updateMessage(
  message.copyWith(status: MessageGroupStatus.delivered),
);

// Remove (triggers fade-out animation)
controller.removeMessage(message.id);

// Replace all (e.g. initial history load)
controller.setMessages(historyList);

---

Delivery status

Each outgoing message can carry a MessageGroupStatus:

Status	Icon
sending	(none)
sent	✓
delivered	✓✓
seen	✓✓ (colored)
error	✗

---

Callbacks

Callback	Description
onSend	User submits text from the composer
onAttachmentTap	User taps the attachment button ("＋")
onMessageTap	Tap on a message bubble
onMessageLongPress	Long-press on a message bubble
onLoadMore	Scrolled to top — load earlier messages

---

API reference

Models

• ChatMessage — Sealed base class
• ChatAuthor — Author with id, displayName, avatarUrl
• ChatController / InMemoryChatController — State management
• ChatOperation — Insert / Remove / Update / Set
• MessageGroupStatus — Delivery status enum

Theme

• ChatTheme — Colors + typography + input decoration
• ChatColors — 12 configurable color slots
• ChatTypography — 4 text styles

Widgets

• ChatView — Main entry point (list + composer)
• ChatMessageList — Animated scrollable list
• ChatComposer — Text input bar
• ChatMessageBubble — Individual message rendering
• ChatScope — InheritedWidget providing config

Config

• ChatBuilders — Widget overrides
• ChatL10n — Localization strings

---

License

MIT — see LICENSE for details.