smart_composer_flutter #

Demo: geniussystems24.github.io/smart_composer_flutter

Skill guide: skills/smart_composer_flutter.md

Screenshots #

Simple composer	Examples

Encode / decode	Drag & drop

A reusable, entity-aware rich composer for Flutter — a faithful port of the GeniusLink SmartComposer React component.

It mixes plain text with inline reference tokens (users, files, invoices, accounts, tasks, tools, commands and any custom type), backed by a human-readable encoded-text source of truth, a React-compatible parser, drag & drop, a read-only preview with remote resolution, modes, triggers, access postures, validation and theming.

The React project is the source of truth. This package matches it visually and behaviourally: same encoded text format, a parser compatible with the React parser, the same models, modes, triggers, examples and interactions.

Features #

• One component, every entity. Plain text interleaved with typed tokens. Adding a new entity type is a single ReferenceRegistry.register(...) call.
• Encoded text is the source of truth. [<prefix><tagType>:<displayText>](valueText) — human-readable, restores the editor without JSON. Byte-for-byte compatible with the React format.
• Triggers — @ people · # records · / commands · $ financial · : tools · word triggers file: / path:. Triggers are data; add your own.
• 9 mode presets — aiPrompt, search, command, note, comment, taskDescription, invoiceNote, financialEntry, message.
• Floating suggestion menu with grouped results, keyboard nav and a custom provider hook (sync or async).
• Drag & drop files / URLs / custom resources → typed tokens, with validation (size, extension, MIME, blocked types).
• Read-only preview (SmartComposerPreview) with per-token remote resolution states: loading / resolved / notFound / permissionDenied / deleted / error + retry.
• Validation — required text, max length, max attachments, required / allowed reference types, entity-state (archived / unavailable) checks.
• Access postures & model picker in the toolbar.
• Theming — GeniusLink dark + light themes out of the box; override any token via ComposerTheme.
• The component never navigates — it fires callbacks; your app decides.

Install #

dependencies:
  smart_composer_flutter:
    path: ../smart_composer_flutter   # or a pub/git ref

import 'package:smart_composer_flutter/smart_composer_flutter.dart';

void main() {
  ReferenceRegistry.ensureDefaults(); // install the default entity types
  runApp(const MyApp());
}

Quick start #

SmartComposer(
  mode: ComposerModes.aiPrompt,
  callbacks: ComposerCallbacks(
    onSubmitted: (value) => print(value.encodedText),
    onReferenceTap: (ref) => openEntity(ref), // app decides navigation
  ),
);

Wrap your app (or any subtree) in a ComposerThemeScope to theme it:

ComposerThemeScope(
  theme: ComposerTheme.dark(), // or ComposerTheme.light()
  child: SmartComposer(mode: ComposerModes.message),
);

Encoded text format #

[<prefix><tagType>:<displayText>](valueText)

[@user:Ahmed](user://user_123)
[#invoice:INV-2026-001](invoice://INV-2026-001)
[$tool:Browser Use](skill://openai-bundled/browser-use/0.1.0-alpha1/browser)
[@file:client-a.pdf](file:///C:/Users/Al-saiary/contracts/client-a.pdf)

• prefix — category / trigger style
• tagType — the authoritative entity type
• displayText — label only (never act on it)
• valueText — the system value to resolve / open

final result = SmartComposerParser.parse(encoded); // segments, tokens, errors, plainText
final value  = SmartComposerValue.fromEncodedText(encoded);
value.toPlainText();
value.toTokenIndex();
value.toStorage();
SmartComposerPlainTextConverter.convert(encoded);
SmartComposerTokenIndex.extract(encoded);

Reserved characters ([ ] ( ) \ and newline) are backslash-escaped inside displayText / valueText; URIs keep their : and / raw. Invalid tokens degrade to plain text and never throw.

Preview & remote resolution #

SmartComposerPreview(
  encodedText: encoded,
  resolver: (token) async {
    final r = await api.lookup(token.valueText);
    if (r == null) return const ResolveResult(state: ResolveState.notFound);
    return ResolveResult(state: ResolveState.resolved, subtitle: r.status);
  },
  onTokenTap: (token) => router.open(token),
);

A demo resolver is included: makeDemoResolver(delay: 800).

Architecture (MVC, matches the React source) #

Flow: types register() → mode preset → controller detects trigger → provider search() → token inserted → validate() → onSubmitted.

Example app #

example/ reproduces the React showcase one-to-one — six tabs: Playground, Examples (8 ready-made configs), Encoding, Drag & Drop, Tests and Docs / API.

cd example
flutter run

Tests #

flutter test

• test/encoding_test.dart — the encoding suite, mirroring React SC.runTests() case-for-case (parser compatibility).
• test/controller_test.dart — controller behaviour (insert, validate, drop, submit).
• test/widget_test.dart — widget rendering & interaction.

The same suite is also available at runtime via runComposerTests() (rendered by the example Tests tab).

AI skill #

A copy-paste agent skill describing how to use this package lives at skills/smart_composer_flutter.md.

License #

MIT © GeniusLink