feat!: store thread settings in Quil Delta document

This commit adds support for saving thread settings in quill delta json
files:

* Thread title.
* Thread type id.
* Required read permission.
* Price.
* Additional options.

using versioned Quill Delta json document.

Since this commit, the quill delta json output is `Map<String, dynamic>`
with two keys:

1. `metadata` - stores all thread settings data (see above).
2. `operations` - stores all quill delta operations (same as previous
   versions).

This document structure provides all data we may access when editing a
thread.

After the document is imported, UI elements in `PostEditPage` will
update to the values in `metadata` section. **Note that values not
present in document will not change.**

Compatibility:

* The `version` field in `metadata` section indicates the document
  structure and allows for future changes.
* Older unversioned Quill Delta documents (List<Map<String, dynamic>>)
  are recognized and imported with empty metadata, preserving existing
  thread settings.
* Older app versions cannot read documents generated by this version.

This commit also added a `tabBar` in bottomsheet.

BREAKING CHANGE: Quill Delta json document generated by this version are
incompatible with older app versions.

Author: realth000

lib/features/editor/widgets/toolbar.dart

@@ -1,12 +1,27 @@
+import 'dart:convert';
+import 'dart:io';
+import 'dart:typed_data';
+
+import 'package:dart_bbcode_parser/dart_bbcode_parser.dart';
+import 'package:dart_quill_delta/dart_quill_delta.dart';
+import 'package:file_picker/file_picker.dart';
 import 'package:flutter/material.dart';
+import 'package:flutter/services.dart' show Clipboard, ClipboardData;
 import 'package:flutter_bbcode_editor/flutter_bbcode_editor.dart';
 import 'package:tsdm_client/constants/layout.dart';
+import 'package:tsdm_client/extensions/date_time.dart';
 import 'package:tsdm_client/features/editor/widgets/color_bottom_sheet.dart';
 import 'package:tsdm_client/features/editor/widgets/emoji_bottom_sheet.dart';
 import 'package:tsdm_client/features/editor/widgets/image_dialog.dart';
 import 'package:tsdm_client/features/editor/widgets/url_dialog.dart';
 import 'package:tsdm_client/features/editor/widgets/username_picker_dialog.dart';
+import 'package:tsdm_client/i18n/strings.g.dart';
+import 'package:tsdm_client/shared/models/models.dart';
+import 'package:tsdm_client/utils/logger.dart';
 import 'package:tsdm_client/utils/platform.dart';
+import 'package:tsdm_client/utils/show_bottom_sheet.dart';
+import 'package:tsdm_client/utils/show_toast.dart';
+import 'package:tsdm_client/widgets/tips_card.dart';
 
 /// Representing all features types.
 enum EditorFeatures {
@@ -99,13 +114,15 @@ enum EditorFeatures {
 }
 
 /// Toolbar for the bbcode editor.
-class EditorToolbar extends StatelessWidget {
+class EditorToolbar extends StatelessWidget with LoggerMixin {
   /// Constructor.
   const EditorToolbar({
     required this.bbcodeController,
     this.disabledFeatures = const {},
     this.afterButtonPressed,
     this.editorFocusNode,
+    this.applyDocumentMetadata,
+    this.collectDocumentMetadata,
     super.key,
   });
 
@@ -126,8 +143,231 @@ class EditorToolbar extends StatelessWidget {
   /// Use This field to update editor focus state.
   final FocusNode? editorFocusNode;
 
+  /// Optional callback function, collect document metadata info from UI.
+  ///
+  /// Use this function to send quill delta json document metadata from outside
+  /// toolbar.
+  final EditorDocumentMetadata Function()? collectDocumentMetadata;
+
+  /// Optional callback function, apply document metadata on UI.
+  ///
+  /// Use this function to update UI with values in metadata.
+  final void Function(EditorDocumentMetadata metadata)? applyDocumentMetadata;
+
   bool _hasFeature(EditorFeatures feature) => !disabledFeatures.contains(feature);
 
+  /// The callback function when portation button is clicked.
+  ///
+  /// Show a bottom sheet provides (copy/paste + import/export) -> (bbcode/quill delta)
+  ///
+  /// To support versioned quill delta document files, provides optional parameters:
+  ///
+  /// * [collectMetadata] callback function that provides document metadata to
+  ///   save in the quill delta document. Caller may use this parameter where
+  ///   UI have document metadata.
+  /// * [applyMetadata] callback function to apply document metadata on UI. Caller
+  ///   may use this parameter where updating metadata in UI is needed.
+  ///
+  /// No matter [collectMetadata] and [applyMetadata] are provided or not, the exported
+  /// quill delta document will always in the latest format, not orignial quill delta json.
+  Future<void> _onPortationButtonClicked(
+    BuildContext context,
+    BBCodeEditorController controller, {
+    EditorDocumentMetadata Function()? collectMetadata,
+    void Function(EditorDocumentMetadata)? applyMetadata,
+  }) async {
+    final tr = context.t.postEditPage.portation;
+
+    final topBar = BottomSheetTopBar(
+      height: 110,
+      alignment: .center,
+      child: Padding(
+        padding: edgeInsetsL12R12,
+        child: Align(
+          child: Column(
+            spacing: 10,
+            children: [
+              TipsCard(
+                iconData: Icons.warning_outlined,
+                tips: '${tr.tip}  ',
+                color: Theme.of(context).colorScheme.onPrimaryContainer,
+                backgroundColor: Theme.of(context).colorScheme.primaryContainer,
+              ),
+              TipsCard(
+                tips: '${tr.typesTip}  ',
+                color: Theme.of(context).colorScheme.onSecondaryContainer,
+                backgroundColor: Theme.of(context).colorScheme.secondaryContainer,
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+
+    await showCustomBottomSheet<void>(
+      title: tr.title,
+      topBar: topBar,
+      context: context,
+      childrenBuilder: (_) => [
+        ListTile(
+          title: Text(tr.copyBBCode),
+          onTap: () async {
+            await Clipboard.setData(ClipboardData(text: controller.toBBCode()));
+            if (!context.mounted) {
+              return;
+            }
+            showSnackBar(context: context, message: context.t.general.copiedToClipboard);
+            Navigator.of(context).pop();
+          },
+        ),
+        ListTile(
+          title: Text(tr.pasteBBCode),
+          onTap: () async {
+            final bbcode = (await Clipboard.getData(Clipboard.kTextPlain))?.text;
+            if (bbcode == null) {
+              return;
+            }
+            try {
+              final delta = parseBBCodeTextToDelta(bbcode.replaceAll('\r', ''));
+              controller.setDocumentFromDelta(delta);
+            } on Exception catch (e, st) {
+              error('failed to paste bbcode: exception thrown');
+              handleRaw(e, st);
+              return;
+            }
+
+            if (!context.mounted) {
+              return;
+            }
+            Navigator.of(context).pop();
+          },
+        ),
+        ListTile(
+          title: Text(tr.exportBBCode),
+          onTap: () async {
+            await _exportFile(context, 'bbcode_', 'txt', controller.toBBCode());
+            if (!context.mounted) {
+              return;
+            }
+            Navigator.of(context).pop();
+          },
+        ),
+        ListTile(
+          title: Text(tr.importBBCode),
+          onTap: () async {
+            final data = await _importFile(context, ['txt']);
+            if (data == null) {
+              return;
+            }
+            if (!context.mounted) {
+              return;
+            }
+            try {
+              final delta = parseBBCodeTextToDelta(data.replaceAll('\r', ''));
+              controller.setDocumentFromDelta(delta);
+            } on Exception catch (e, st) {
+              error('failed to import bbcode: exception thrown');
+              handleRaw(e, st);
+              return;
+            }
+            Navigator.of(context).pop();
+          },
+        ),
+        ListTile(
+          title: Text(tr.copyQuilllDelta),
+          onTap: () async {
+            final data = EditorDocument.build(collectMetadata?.call(), controller.toQuillDeltaJson());
+            await Clipboard.setData(ClipboardData(text: data.toJson()));
+            if (!context.mounted) {
+              return;
+            }
+            showSnackBar(context: context, message: context.t.general.copiedToClipboard);
+            Navigator.of(context).pop();
+          },
+        ),
+        ListTile(
+          title: Text(tr.pasteQuillDelta),
+          onTap: () async {
+            final data = (await Clipboard.getData(Clipboard.kTextPlain))?.text;
+            if (data == null) {
+              return;
+            }
+            try {
+              final d = jsonDecode(data.replaceAll('\r', ''));
+              if (d is List<Map<String, dynamic>>) {
+                // Not versioned.
+                final delta = Delta.fromJson(d);
+                controller.setDocumentFromDelta(delta);
+              } else if (d is Map<String, dynamic>) {
+                // Versioned.
+                final doc = EditorDocumentMapper.fromMap(d);
+                applyMetadata?.call(doc.metadata);
+                final delta = Delta.fromJson(doc.operations);
+                controller.setDocumentFromDelta(delta);
+              } else {
+                throw FormatException('invalid quill delta document type ${d.runtimeType}');
+              }
+            } on Exception catch (e, st) {
+              error('failed to paste quill delta: exception thrown');
+              handleRaw(e, st);
+              return;
+            }
+
+            if (!context.mounted) {
+              return;
+            }
+            Navigator.of(context).pop();
+          },
+        ),
+        ListTile(
+          title: Text(tr.exportQuillDelta),
+          onTap: () async {
+            final data = EditorDocument.build(collectMetadata?.call(), controller.toQuillDeltaJson());
+            await _exportFile(context, 'quilldata_', 'json', data.toJson());
+            if (!context.mounted) {
+              return;
+            }
+            Navigator.of(context).pop();
+          },
+        ),
+        ListTile(
+          title: Text(tr.importQuillDelta),
+          onTap: () async {
+            final data = await _importFile(context, ['json']);
+            if (data == null) {
+              return;
+            }
+            if (!context.mounted) {
+              return;
+            }
+
+            try {
+              final d = jsonDecode(data.replaceAll('\r', ''));
+              if (d is List<dynamic>) {
+                // Not versioned.
+                final delta = Delta.fromJson(d);
+                controller.setDocumentFromDelta(delta);
+              } else if (d is Map<String, dynamic>) {
+                // Versioned.
+                final doc = EditorDocumentMapper.fromMap(d);
+                applyMetadata?.call(doc.metadata);
+                final delta = Delta.fromJson(doc.operations);
+                controller.setDocumentFromDelta(delta);
+              } else {
+                throw FormatException('invalid quill delta document type ${d.runtimeType}');
+              }
+            } on Exception catch (e, st) {
+              error('failed to import quill delta: exception thrown');
+              handleRaw(e, st);
+              return;
+            }
+            Navigator.of(context).pop();
+          },
+        ),
+      ],
+    );
+  }
+
   @override
   Widget build(BuildContext context) {
     final toolbar = BBCodeEditorToolbar(
@@ -141,6 +381,12 @@ class EditorToolbar extends StatelessWidget {
           showColorPicker(context, initialColor, PickerType.background),
       imagePicker: (context, url, width, height) => showImagePicker(context, url: url, width: width, height: height),
       usernamePicker: showUsernamePickerDialog,
+      onPortationButtonClicked: (_, controller) async => _onPortationButtonClicked(
+        context,
+        controller,
+        collectMetadata: collectDocumentMetadata,
+        applyMetadata: applyDocumentMetadata,
+      ),
       // Features.
       showUndo: _hasFeature(EditorFeatures.undo),
       showRedo: _hasFeature(EditorFeatures.redo),
@@ -178,3 +424,22 @@ class EditorToolbar extends StatelessWidget {
     return toolbar;
   }
 }
+
+Future<String?> _importFile(BuildContext context, List<String> exts) async {
+  final result = await FilePicker.platform.pickFiles(type: FileType.custom, allowedExtensions: exts);
+  if (result == null) {
+    return null;
+  }
+  return File(result.files.single.path!).readAsString();
+}
+
+Future<void> _exportFile(BuildContext context, String prefix, String ext, String data) async {
+  final result = await FilePicker.platform.saveFile(
+    fileName: '$prefix${DateTime.now().yyyyMMDDHHMMSS()}.$ext',
+    bytes: Uint8List.fromList(utf8.encode(data)),
+  );
+  if (result == null) {
+    return;
+  }
+  await File(result).writeAsString(data);
+}