docs(readme): update the extensions package to document the Rich Text Paste feature on web

flutter_quill_extensions/README.md

@@ -19,6 +19,7 @@ Check [Flutter Quill](https://github.com/singerdmx/flutter-quill) for details of
     - [📦 Embed Blocks](#-embed-blocks)
     - [🔍 Element properties](#-element-properties)
     - [🔧 Custom Element properties](#-custom-element-properties)
+    - [📝 Rich Text Paste Feature](#-rich-text-paste-feature)
     - [🖼️ Image Assets](#️-image-assets)
     - [🎯 Drag and drop feature](#-drag-and-drop-feature)
   - [💡 Features](#-features)
@@ -73,7 +74,7 @@ The package uses the following plugins:
    handle that if you plan on adding support for the desktop, this may change in the future, and for more info follow
    this [link](https://pub.dev/packages/image_picker#windows-macos-and-linux)
 5. [`super_clipboard`](https://pub.dev/packages/super_clipboard) which needs some setup on Android only, it's used to
-   support copying images and pasting them into editor then you must set up it, open the page in pub.dev and read
+   support copying images and pasting them into editor, open the page in pub.dev and read
    the `README.md` or click on this [link](https://pub.dev/packages/super_clipboard#android-support) to get the
    instructions.
 
@@ -98,42 +99,29 @@ The minSdkVersion is `23` as `super_clipboard` requires it
 
 Start using the package in 3 steps:
 
-1. Be sure to follow the [Installation](#installation) section.
-2. This package already include `super_clipboard` and will be used internally in this package, to use it
-   in `flutter_quill`, call this function before using any of the widgets or functionalities
+Be sure to follow the [Installation](#installation) section.
 
-    ```dart
-    FlutterQuillExtensions.useSuperClipboardPlugin();
-    ```
-
-   `super_clipboard` is comprehensive plugin that provides many clipboard features for reading and writing of rich text,
-   images and other formats.
+Set the `embedBuilders` and `embedToolbar` params in configurations of `QuillEditor` and `QuillToolbar`.
 
-   Executing this function will allow `flutter_quill` to use modern rich text features to paste HTML and Markdown,
-   support for Gif files, and other formats.
-
-3. Set the `embedBuilders` and `embedToolbar` params in configurations of `QuillEditor` and `QuillToolbar` with the
-   values provided by this repository.
+**Quill Toolbar**:
+```dart
+QuillToolbar(
+  configurations: QuillToolbarConfigurations(
+    embedButtons: FlutterQuillEmbeds.toolbarButtons(),
+  ),
+),
+```
 
-   **Quill Toolbar**:
-    ```dart
-    QuillToolbar(
-      configurations: QuillToolbarConfigurations(
-        embedButtons: FlutterQuillEmbeds.toolbarButtons(),
-      ),
+**Quill Editor**:
+```dart
+Expanded(
+  child: QuillEditor.basic(
+    configurations: QuillEditorConfigurations(
+      embedBuilders: kIsWeb ? FlutterQuillEmbeds.editorWebBuilders() : FlutterQuillEmbeds.editorBuilders(),
     ),
-    ```
-
-   **Quill Editor**
-    ```dart
-    Expanded(
-      child: QuillEditor.basic(
-        configurations: QuillEditorConfigurations(
-          embedBuilders: kIsWeb ? FlutterQuillEmbeds.editorWebBuilders() : FlutterQuillEmbeds.editorBuilders(),
-        ),
-      ),
-    )
-    ```
+  ),
+)
+```
 
 ## ⚙️ Configurations
 
@@ -182,6 +170,50 @@ Define flutterAlignment` as follows:
 
 This works for all platforms except Web
 
+### 📝 Rich Text Paste Feature
+
+The Rich Text Pasting feature requires native code to access
+the `Clipboard` data as HTML, the plugin `super_clipboard` is required on all platforms except Web.
+
+This package already includes `super_clipboard` and will be used internally in this package, to use it
+in `flutter_quill`, call this function before using any of the widgets or functionalities:
+
+```dart
+FlutterQuillExtensions.useSuperClipboardPlugin();
+```
+
+`super_clipboard` is a comprehensive plugin that provides many clipboard features for reading and writing rich text,
+images and other formats.
+
+Executing this function will allow `flutter_quill` to use modern rich text features to paste HTML and Markdown,
+support for GIF files, and other formats.
+
+> [!IMPORTANT]
+> On web platforms, you can only get the HTML from `Clipboard` on the
+> `paste` event, `super_clipboard`, or any plugin is not required.
+> The paste feature will not work using the standard paste hotkey logic.
+> As such, you will be unable to use the **Rich Text Paste Feature** on a button or in the web app itself.
+> So you might want to either display a dialog when pressing the paste button that explains the limitation and shows the hotkey they need to press in order to paste or develop an extension for the browser that bypasses this limitation similarly to **Google Docs** and provide a link to install the browser extension.
+> See [Issue #1998](https://github.com/singerdmx/flutter-quill/issues/1998) for more details.
+
+
+To register the `paste` event:
+
+```dart
+import 'package:web/web.dart';
+
+EventStreamProviders.pasteEvent.forTarget(web.document).listen((e) {
+  final html = e.clipboardData?.getData('text/html');
+  // Convert the HTML to Delta and paste it into the editor
+});
+```
+
+Don't forget to cancel the `StreamSubscription` when no longer needed.
+
+> [!NOTE]
+> We're still planning on how this should be implemented in
+> [Issue #1998](https://github.com/singerdmx/flutter-quill/issues/1998).
+
 ### 🖼️ Image Assets
 
 If you want to use image assets in the Quill Editor, you need to make sure your assets folder is `assets` otherwise: