Feature/flutter example (#2)

* doc
* flutter example

Author: MattiaPispisa

.vscode/tasks.json

@@ -61,6 +61,43 @@
         "focus": false,
         "clear": true
       }
+    },
+    {
+      "label": "[rich_i18n] Run Example",
+      "type": "shell",
+      "command": "dart",
+      "args": [
+        "run",
+        "example/main.dart"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}/rich_i18n"
+      },
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "focus": false,
+        "clear": true
+      }
+    },
+    {
+      "label": "[flutter_example] Run Flutter Example",
+      "type": "shell",
+      "command": "flutter",
+      "args": [
+        "run"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}/rich_i18n/flutter_example"
+      },
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared",
+        "focus": false,
+        "clear": true
+      }
     }
   ]
 }

assets/rich_text_flutter_example.png

@@ -1,3 +1,17 @@
+## [0.1.1](https://github.com/MattiaPispisa/rich_i18n/tree/rich_i18n-v0.1.1/rich_i18n)
+
+[compare to previous release](https://github.com/MattiaPispisa/rich_i18n/compare/rich_i18n-v0.1.0...rich_i18n-v0.1.1)
+
+
+**Date:** 2026-01-10
+
+### Added
+- Flutter example app in the `flutter_example` directory.
+
+### Changed
+
+- chore: documentation
+
 ## [0.1.0](https://github.com/MattiaPispisa/rich_i18n/tree/rich_i18n-v0.1.0/rich_i18n)
 **Date:** 2026-01-10
 

rich_i18n/CHANGELOG.md

@@ -82,6 +82,21 @@ final items = tryGetRichTextSync('Invalid <b>XML');
 - Consecutive text segments with the same style are automatically merged
 - Empty tags are ignored (no unnecessary items created)
 
+## Flutter Example
+
+A complete Flutter example app is available in the `flutter_example` directory,
+demonstrating how to convert the parsed `RichTextItem` objects into Flutter's
+`TextSpan` widgets for rendering rich text in Flutter applications.
+
+The example includes an interactive editor where you can:
+- Edit XML source with rich text tags
+- See the rendered preview in real-time
+- Test various formatting options (bold, underline, colors, links, etc.)
+
+<img width="500" alt="rich_text_flutter_example" src="https://raw.githubusercontent.com/MattiaPispisa/rich_i18n/main/assets/rich_text_flutter_example.png">
+
+To run the Flutter example:
+
 ## Why not Flutter?
 
 This library is intentionally **framework-agnostic** and has no Flutter dependency:

rich_i18n/README.md

@@ -1,5 +1,7 @@
 // ignore_for_file: avoid_print just for example purposes
 
+import 'dart:async';
+
 import 'package:rich_i18n/rich_i18n.dart';
 
 void main() async {
@@ -9,7 +11,7 @@ void main() async {
   print('');
 
   // Example 1: Basic text parsing with bold tag
-  _sectionPrintLayout(
+  await _sectionPrintLayout(
     title: 'Example 1: Basic bold text',
     body: () {
       final basicItems = tryGetRichTextSync('Hello <b>World</b>!');
@@ -24,7 +26,7 @@ void main() async {
   );
 
   // Example 2: Nested tags
-  _sectionPrintLayout(
+  await _sectionPrintLayout(
     title: 'Example 2: Nested tags (bold and underline)',
     body: () {
       final nestedItems = tryGetRichTextSync(
@@ -41,7 +43,7 @@ void main() async {
   );
 
   // Example 3: Multiple text styles
-  _sectionPrintLayout(
+  await _sectionPrintLayout(
     title: 'Example 3: Multiple text styles',
     body: () {
       final stylesItems = tryGetRichTextSync(
@@ -64,7 +66,7 @@ void main() async {
   );
 
   // Example 4: Span with attributes (color, font size, etc.)
-  _sectionPrintLayout(
+  await _sectionPrintLayout(
     title: 'Example 4: Span with attributes',
     body: () {
       final spanItems = tryGetRichTextSync(
@@ -82,7 +84,7 @@ void main() async {
     },
   );
   // Example 5: Background color and font family
-  _sectionPrintLayout(
+  await _sectionPrintLayout(
     title: 'Example 5: Background color and font family',
     body: () {
       final styledItems = tryGetRichTextSync(
@@ -99,7 +101,7 @@ void main() async {
     },
   );
   // Example 6: Links
-  _sectionPrintLayout(
+  await _sectionPrintLayout(
     title: 'Example 6: Hyperlinks',
     body: () {
       final linkItems = tryGetRichTextSync(
@@ -115,7 +117,7 @@ void main() async {
   );
 
   // Example 7: Complex nested structure
-  _sectionPrintLayout(
+  await _sectionPrintLayout(
     title: 'Example 7: Complex nested structure',
     body: () {
       final complexItems = tryGetRichTextSync(
@@ -136,7 +138,7 @@ void main() async {
   );
 
   // Example 8: Error handling with tryGetRichTextSync (returns null)
-  _sectionPrintLayout(
+  await _sectionPrintLayout(
     title: 'Example 8: Error handling (invalid XML)',
     body: () {
       final invalidItems = tryGetRichTextSync('Invalid <b>unclosed tag');
@@ -147,7 +149,7 @@ void main() async {
   );
 
   // Example 9: Verbose mode with error reporting
-  await _sectionPrintLayoutAsync(
+  await _sectionPrintLayout(
     title: 'Example 9: Verbose mode (with descriptors)',
     body: () async {
       try {
@@ -178,7 +180,7 @@ void main() async {
   );
 
   // Example 10: Empty tags are ignored (merged)
-  _sectionPrintLayout(
+  await _sectionPrintLayout(
     title: 'Example 10: Consecutive same-style segments are merged',
     body: () {
       final mergedItems = tryGetRichTextSync('<b>hello</b><b> world</b>');
@@ -197,22 +199,12 @@ void main() async {
   print('=' * 60);
 }
 
-void _sectionPrintLayout({
-  required String title,
-  void Function()? body,
-}) {
-  print(title);
-  print('-' * 60);
-  body?.call();
-  print('');
-}
-
-Future<void> _sectionPrintLayoutAsync({
+Future<void> _sectionPrintLayout({
   required String title,
-  required Future<void> Function() body,
+  FutureOr<void> Function()? body,
 }) async {
   print(title);
   print('-' * 60);
-  await body();
+  await body?.call();
   print('');
 }

rich_i18n/example/main.dart

@@ -0,0 +1,3 @@
+{
+  "flutter": "stable"
+}

rich_i18n/flutter_example/.fvmrc

@@ -0,0 +1,48 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.build/
+.buildlog/
+.history
+.svn/
+.swiftpm/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+/coverage/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release
+
+# FVM Version Cache
+.fvm/

rich_i18n/flutter_example/.gitignore

@@ -0,0 +1,45 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "f6ff1529fd6d8af5f706051d9251ac9231c83407"
+  channel: "stable"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+    - platform: android
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+    - platform: ios
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+    - platform: linux
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+    - platform: macos
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+    - platform: web
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+    - platform: windows
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

rich_i18n/flutter_example/.metadata

@@ -0,0 +1,16 @@
+# flutter_example
+
+A new Flutter project.
+
+## Getting Started
+
+This project is a starting point for a Flutter application.
+
+A few resources to get you started if this is your first Flutter project:
+
+- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
+- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
+
+For help getting started with Flutter development, view the
+[online documentation](https://docs.flutter.dev/), which offers tutorials,
+samples, guidance on mobile development, and a full API reference.

rich_i18n/flutter_example/README.md

@@ -0,0 +1,4 @@
+include: package:flutter_lints/flutter.yaml
+
+linter:
+  rules: