@capawesome/capacitor-clipboard 0.0.1 → 0.1.1

package/README.md

@@ -21,9 +21,14 @@ Capacitor plugin to read from and write to the system clipboard.
 
 Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
 
-## Newsletter
+## Use Cases
 
-Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+The Clipboard plugin is typically used whenever an app lets users copy or paste content, for example:
+
+- **Copy to clipboard buttons**: Let users copy coupon codes, invite links, or wallet addresses with one tap.
+- **Paste support**: Read text, URLs, or images from the clipboard into your app, for example into a form or editor.
+- **Sharing images**: Copy a generated image (such as a QR code or chart) so users can paste it into other apps.
+- **Rich text workflows**: Copy formatted HTML content with a plain-text fallback for apps that cannot handle HTML.
 
 ## Compatibility
 
@@ -67,12 +72,26 @@ No configuration required for this plugin.
 
 ## Usage
 
+The following examples show how to write text, HTML, images, and URLs to the clipboard, and how to read its current content.
+
+### Write text to the clipboard
+
+Copy plain text to the system clipboard:
+
 ```typescript
 import { Clipboard } from '@capawesome/capacitor-clipboard';
 
 const writeText = async () => {
   await Clipboard.write({ text: 'Hello World' });
 };
+```
+
+### Write HTML with a plain-text fallback
+
+Copy HTML content and combine it with `text` to provide a plain-text fallback for apps that cannot handle HTML content:
+
+```typescript
+import { Clipboard } from '@capawesome/capacitor-clipboard';
 
 const writeHtml = async () => {
   await Clipboard.write({
@@ -80,16 +99,40 @@ const writeHtml = async () => {
     text: 'Hello World',
   });
 };
+```
+
+### Write an image to the clipboard
+
+Copy a real image (not just a data URL as plain text) by passing a Base64-encoded data URL:
+
+```typescript
+import { Clipboard } from '@capawesome/capacitor-clipboard';
 
 const writeImage = async () => {
   await Clipboard.write({
     image: 'data:image/png;base64,iVBORw0KGgo...',
   });
 };
+```
+
+### Write a URL to the clipboard
+
+Copy a URL as a native URL clipboard item:
+
+```typescript
+import { Clipboard } from '@capawesome/capacitor-clipboard';
 
 const writeUrl = async () => {
   await Clipboard.write({ url: 'https://capawesome.io' });
 };
+```
+
+### Read the clipboard content
+
+Read the current content of the system clipboard. The result contains the content type (text, HTML, image, or URL) and the value. Note that on Android, reading the clipboard is only possible while the app is in the foreground, and on iOS, a system paste notification is displayed:
+
+```typescript
+import { Clipboard } from '@capawesome/capacitor-clipboard';
 
 const read = async () => {
   const { type, value } = await Clipboard.read();
@@ -211,6 +254,45 @@ This plugin is a drop-in alternative to the official [`@capacitor/clipboard`](ht
 | —                                          | `write({ html: '<b>Hello</b>', text: 'Hello' })`       |
 | `read() → { value, type: 'text/plain' }`   | `read() → { value, type: 'TEXT' }`                     |
 
+## FAQ
+
+### How is this plugin different from other similar plugins?
+
+It supports far more than plain text — copy and paste images, HTML with a plain-text fallback, and native URL items, with reliable real image handling on Android, iOS, and the web. The API is fully typed and actively maintained against the latest OS and framework versions, and it uses only official platform APIs so it stays safe for App Store and Google Play submissions. If you only ever copy plain text, a simpler setup is perfectly fine; if you need rich content and consistent behavior across every platform, this plugin is designed for exactly that.
+
+### Why is a notification shown when my app reads the clipboard?
+
+On iOS 14 and later, the system shows a paste notification banner every time the clipboard is read. On Android 12 (API level 31) and later, the system shows a toast message when an app reads clipboard content that was written by another app. Both are expected platform behavior and cannot be suppressed.
+
+### Why does reading the clipboard fail on Android?
+
+On Android 10 (API level 29) and later, apps can only read the clipboard while they are in the foreground and have input focus. The `read()` method rejects otherwise, so make sure to only call it in response to a user interaction while the app is visible.
+
+### Can I write multiple content types at once?
+
+No, exactly one of `text`, `html`, `image` or `url` must be provided when calling `write(...)`. The only exception is that `html` may additionally be combined with `text` to provide a plain-text fallback for apps that cannot handle HTML content.
+
+### How are images handled by this plugin?
+
+Images are written to the clipboard as real images, not just data URLs as plain text, by passing a Base64-encoded data URL to `write(...)`. When reading, images are also returned as a Base64-encoded data URL. See the [usage examples](#write-an-image-to-the-clipboard) above.
+
+### How is this plugin different from the official `@capacitor/clipboard` plugin?
+
+This plugin is a drop-in alternative to the official `@capacitor/clipboard` plugin with real image support on Android and HTML support on all platforms. Only a few method options differ, see the [migration table](#migrating-from-capacitorclipboard) above.
+
+### Can I use this plugin with Ionic, React, Vue or Angular?
+
+Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.
+
+## Related Plugins
+
+- [Share Target](https://capawesome.io/docs/sdks/capacitor/share-target/): Receive content such as text, links, and files from other apps.
+- [Text Interaction](https://capawesome.io/docs/sdks/capacitor/text-interaction/): Enable and disable text interaction (selection, magnifier, callout menu) in the app's WebView.
+
+## Newsletter
+
+Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/clipboard/CHANGELOG.md).

package/android/build.gradle

@@ -30,7 +30,7 @@ android {
     buildTypes {
         release {
             minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
         }
     }
     lintOptions {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capawesome/capacitor-clipboard",
-  "version": "0.0.1",
-  "description": "Capacitor plugin to read from and write to the system clipboard.",
+  "version": "0.1.1",
+  "description": "Capacitor plugin to read from and write to the system clipboard on Android, iOS, and Web.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",
@@ -40,7 +40,14 @@
     "native",
     "clipboard",
     "copy",
-    "paste"
+    "paste",
+    "capacitor-plugin",
+    "copy to clipboard",
+    "clipboard image",
+    "clipboard html",
+    "rich text",
+    "pasteboard",
+    "copy paste"
   ],
   "scripts": {
     "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",