@capgo/capacitor-pretty-toast 8.1.0

package/README.md

@@ -0,0 +1,341 @@
+# @capgo/capacitor-pretty-toast
+
+Native-first pretty toast notifications for Capacitor and the web.
+
+capacitor-pretty-toast.mov
+
+![Pretty Toast Hero](./media/pretty-toast-hero.png)
+
+This package keeps the familiar `toast.*` surface from `react-native-pretty-toast`, but ships as a Capacitor plugin with:
+
+- native overlays on iOS and Android.
+- a DOM renderer on web.
+- queueing, `force`, `update`, `dismiss`, `dismissAll`, and `promise`
+- symbol icons, raw SVG through `icon`, and URI-based images through `iconSource`
+
+## Install
+
+```bash
+bun add @capgo/capacitor-pretty-toast
+```
+
+Then sync native platforms:
+
+```bash
+bunx cap sync
+```
+
+## Usage
+
+```ts
+import { toast } from '@capgo/capacitor-pretty-toast';
+
+toast.success('Saved', {
+  message: 'Your changes are already on disk.',
+});
+
+const id = toast.loading('Uploading', {
+  message: 'This toast stays visible until you update it.',
+});
+
+setTimeout(() => {
+  toast.update(id, {
+    title: 'Upload complete',
+    message: 'Updated in place without replaying the enter animation.',
+    icon: 'checkmark.circle.fill',
+    autoDismiss: true,
+  });
+}, 1500);
+```
+
+## API
+
+<docgen-index>
+
+* [`show(...)`](#show)
+* [`success(...)`](#success)
+* [`error(...)`](#error)
+* [`info(...)`](#info)
+* [`warning(...)`](#warning)
+* [`loading(...)`](#loading)
+* [`update(...)`](#update)
+* [`promise(...)`](#promise)
+* [`dismiss(...)`](#dismiss)
+* [`dismissAll()`](#dismissall)
+* [Interfaces](#interfaces)
+* [Type Aliases](#type-aliases)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+Public toast controller exposed as `toast`.
+
+### show(...)
+
+```typescript
+show(config: ToastConfig, options?: ShowOptions | undefined) => string
+```
+
+Show a custom toast and return its id.
+
+| Param         | Type                                                |
+| ------------- | --------------------------------------------------- |
+| **`config`**  | <code><a href="#toastconfig">ToastConfig</a></code> |
+| **`options`** | <code><a href="#showoptions">ShowOptions</a></code> |
+
+**Returns:** <code>string</code>
+
+--------------------
+
+
+### success(...)
+
+```typescript
+success(title: string, config?: ToastConfig | undefined, options?: ShowOptions | undefined) => string
+```
+
+Show a success toast.
+
+| Param         | Type                                                |
+| ------------- | --------------------------------------------------- |
+| **`title`**   | <code>string</code>                                 |
+| **`config`**  | <code><a href="#toastconfig">ToastConfig</a></code> |
+| **`options`** | <code><a href="#showoptions">ShowOptions</a></code> |
+
+**Returns:** <code>string</code>
+
+--------------------
+
+
+### error(...)
+
+```typescript
+error(title: string, config?: ToastConfig | undefined, options?: ShowOptions | undefined) => string
+```
+
+Show an error toast.
+
+| Param         | Type                                                |
+| ------------- | --------------------------------------------------- |
+| **`title`**   | <code>string</code>                                 |
+| **`config`**  | <code><a href="#toastconfig">ToastConfig</a></code> |
+| **`options`** | <code><a href="#showoptions">ShowOptions</a></code> |
+
+**Returns:** <code>string</code>
+
+--------------------
+
+
+### info(...)
+
+```typescript
+info(title: string, config?: ToastConfig | undefined, options?: ShowOptions | undefined) => string
+```
+
+Show an informational toast.
+
+| Param         | Type                                                |
+| ------------- | --------------------------------------------------- |
+| **`title`**   | <code>string</code>                                 |
+| **`config`**  | <code><a href="#toastconfig">ToastConfig</a></code> |
+| **`options`** | <code><a href="#showoptions">ShowOptions</a></code> |
+
+**Returns:** <code>string</code>
+
+--------------------
+
+
+### warning(...)
+
+```typescript
+warning(title: string, config?: ToastConfig | undefined, options?: ShowOptions | undefined) => string
+```
+
+Show a warning toast.
+
+| Param         | Type                                                |
+| ------------- | --------------------------------------------------- |
+| **`title`**   | <code>string</code>                                 |
+| **`config`**  | <code><a href="#toastconfig">ToastConfig</a></code> |
+| **`options`** | <code><a href="#showoptions">ShowOptions</a></code> |
+
+**Returns:** <code>string</code>
+
+--------------------
+
+
+### loading(...)
+
+```typescript
+loading(title: string, config?: ToastConfig | undefined, options?: ShowOptions | undefined) => string
+```
+
+Show a loading toast. Loading toasts do not auto-dismiss by default.
+
+| Param         | Type                                                |
+| ------------- | --------------------------------------------------- |
+| **`title`**   | <code>string</code>                                 |
+| **`config`**  | <code><a href="#toastconfig">ToastConfig</a></code> |
+| **`options`** | <code><a href="#showoptions">ShowOptions</a></code> |
+
+**Returns:** <code>string</code>
+
+--------------------
+
+
+### update(...)
+
+```typescript
+update(id: string, partial: ToastConfig) => void
+```
+
+Update an existing toast by id.
+
+| Param         | Type                                                |
+| ------------- | --------------------------------------------------- |
+| **`id`**      | <code>string</code>                                 |
+| **`partial`** | <code><a href="#toastconfig">ToastConfig</a></code> |
+
+--------------------
+
+
+### promise(...)
+
+```typescript
+promise<T>(promise: Promise<T>, messages: PromiseMessages<T>) => Promise<T>
+```
+
+Show a loading toast while a promise is pending, then update it for success or error.
+
+| Param          | Type                                                                 |
+| -------------- | -------------------------------------------------------------------- |
+| **`promise`**  | <code>Promise&lt;T&gt;</code>                                        |
+| **`messages`** | <code><a href="#promisemessages">PromiseMessages</a>&lt;T&gt;</code> |
+
+**Returns:** <code>Promise&lt;T&gt;</code>
+
+--------------------
+
+
+### dismiss(...)
+
+```typescript
+dismiss(id?: string | undefined) => void
+```
+
+Dismiss one toast by id, or the current toast when no id is provided.
+
+| Param    | Type                |
+| -------- | ------------------- |
+| **`id`** | <code>string</code> |
+
+--------------------
+
+
+### dismissAll()
+
+```typescript
+dismissAll() => void
+```
+
+Dismiss the current toast and clear the queue.
+
+--------------------
+
+
+### Interfaces
+
+
+#### ToastConfig
+
+| Prop                            | Type                                                | Description                                                                                                                                                            |
+| ------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`id`**                        | <code>string</code>                                 | Optional stable toast id. A generated id is returned when omitted.                                                                                                     |
+| **`icon`**                      | <code>string</code>                                 | Accepts either an SF-symbol-like identifier or raw SVG markup. SVG mode is enabled only when the string starts with `&lt;svg` after trim.                              |
+| **`iconSource`**                | <code><a href="#iconsource">IconSource</a></code>   | URI-like image source. Supports `https://`, `http://`, `file://`, absolute file paths, `data:` URLs, `blob:` URLs, or `{ uri }`. `iconSource` always wins over `icon`. |
+| **`title`**                     | <code>string</code>                                 | Main toast title.                                                                                                                                                      |
+| **`message`**                   | <code>string</code>                                 | Secondary toast message.                                                                                                                                               |
+| **`duration`**                  | <code>number</code>                                 | Auto-dismiss delay in milliseconds.                                                                                                                                    |
+| **`autoDismiss`**               | <code>boolean</code>                                | Whether the toast dismisses itself after `duration`.                                                                                                                   |
+| **`enableSwipeDismiss`**        | <code>boolean</code>                                | Whether swipe-to-dismiss is enabled on native overlays.                                                                                                                |
+| **`accentColor`**               | <code>string</code>                                 | CSS-style accent color used by native/web renderers.                                                                                                                   |
+| **`strokeColor`**               | <code>string</code>                                 | CSS-style border/stroke color.                                                                                                                                         |
+| **`disableBackdropSampling`**   | <code>boolean</code>                                | Disable Android/iOS backdrop sampling behind the toast.                                                                                                                |
+| **`action`**                    | <code><a href="#toastaction">ToastAction</a></code> | Optional action button configuration.                                                                                                                                  |
+| **`accessibilityAnnouncement`** | <code>string</code>                                 | Text announced to assistive technologies when the toast is shown.                                                                                                      |
+| **`onPress`**                   | <code>(() =&gt; void)</code>                        | Called when the toast body is pressed.                                                                                                                                 |
+| **`onShow`**                    | <code>(() =&gt; void)</code>                        | Called when the toast becomes visible.                                                                                                                                 |
+| **`onHide`**                    | <code>(() =&gt; void)</code>                        | Called when the toast is dismissed.                                                                                                                                    |
+| **`onAutoDismiss`**             | <code>(() =&gt; void)</code>                        | Called when the toast is dismissed by its timer.                                                                                                                       |
+
+
+#### ToastAction
+
+| Prop          | Type                       | Description                                  |
+| ------------- | -------------------------- | -------------------------------------------- |
+| **`label`**   | <code>string</code>        | Text shown for the native/web action button. |
+| **`onPress`** | <code>() =&gt; void</code> | Called when the action button is pressed.    |
+
+
+#### ShowOptions
+
+| Prop        | Type                 | Description                                              |
+| ----------- | -------------------- | -------------------------------------------------------- |
+| **`force`** | <code>boolean</code> | Dismiss the current toast and show this one immediately. |
+
+
+### Type Aliases
+
+
+#### IconSource
+
+<code>string | { uri: string }</code>
+
+
+#### PromiseMessages
+
+<code>{ loading: string | <a href="#toastconfig">ToastConfig</a>; success: string | ((value: T) =&gt; string | <a href="#toastconfig">ToastConfig</a>); error: string | ((error: unknown) =&gt; string | <a href="#toastconfig">ToastConfig</a>); }</code>
+
+</docgen-api>
+
+Notes:
+
+- Raw SVG is accepted only through `icon`.
+- `iconSource` always takes precedence over `icon`.
+- `toast.loading()` defaults `autoDismiss` to `false`.
+
+## Example App
+
+The repo includes [`example-app/`](./example-app), a Vite-based Capacitor app with demos for:
+
+- every `toast.*` method
+- queueing and `force`
+- live `update`
+- `dismiss` and `dismissAll`
+- `promise`
+- symbol icons
+- raw SVG icons
+- remote and data-URL `iconSource` values
+- repeatable capture modes with `?demo=hero`, `?demo=flow`, and `?demo=update`
+
+`?demo=flow` is the promo enter/exit morph used in the README video.
+The shipped video shows both the Android cutout path and the centered island-style path side by side.
+
+Run it locally:
+
+```bash
+cd example-app
+bun install
+bun run start
+```
+
+## Development
+
+```bash
+bun install
+bun run build
+bun test
+bun run verify
+```

package/android/build.gradle

@@ -0,0 +1,71 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+    mockitoVersion = project.hasProperty('mockitoVersion') ? rootProject.ext.mockitoVersion : '5.14.2'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:2.3.20"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.android'
+
+android {
+    namespace = "com.toast"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdk project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdk project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget = JvmTarget.JVM_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "androidx.dynamicanimation:dynamicanimation:1.0.0"
+
+    testImplementation "junit:junit:$junitVersion"
+    testImplementation "org.mockito:mockito-core:$mockitoVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+</manifest>

package/android/src/main/java/com/toast/PrettyToastPlugin.kt

@@ -0,0 +1,197 @@
+package com.toast
+
+import android.app.Activity
+import android.graphics.Color
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+
+@CapacitorPlugin(name = "PrettyToast")
+class PrettyToastPlugin : Plugin() {
+    private var overlay: ToastOverlay? = null
+    private var overlayActivity: Activity? = null
+    private var currentToastId: String? = null
+
+    @PluginMethod
+    fun showCurrentToast(call: PluginCall) {
+        val payload = parsePayload(call) ?: return
+        val overlay = ensureOverlay() ?: run {
+            call.reject("Activity is unavailable")
+            return
+        }
+
+        currentToastId = payload.id
+
+        activity?.runOnUiThread {
+            overlay.show(
+                payload.icon,
+                payload.iconUri,
+                payload.title,
+                payload.message,
+                payload.duration,
+                payload.autoDismiss,
+                payload.enableSwipeDismiss,
+                payload.useDynamicIsland,
+                payload.accentColor,
+                payload.strokeColor,
+                payload.disableBackdropSampling,
+                payload.actionLabel,
+                payload.accessibilityAnnouncement,
+            )
+            call.resolve()
+        }
+    }
+
+    @PluginMethod
+    fun updateCurrentToast(call: PluginCall) {
+        val payload = parsePayload(call) ?: return
+        if (currentToastId != null && currentToastId != payload.id) {
+            call.resolve()
+            return
+        }
+
+        val overlay = ensureOverlay() ?: run {
+            call.reject("Activity is unavailable")
+            return
+        }
+
+        activity?.runOnUiThread {
+            overlay.update(
+                payload.icon,
+                payload.iconUri,
+                payload.title,
+                payload.message,
+                payload.duration,
+                payload.autoDismiss,
+                payload.accentColor,
+                payload.strokeColor,
+                payload.disableBackdropSampling,
+                payload.actionLabel,
+            )
+            call.resolve()
+        }
+    }
+
+    @PluginMethod
+    fun dismissCurrentToast(call: PluginCall) {
+        val requestedId = call.getString("id")
+        if (requestedId != null && currentToastId != null && requestedId != currentToastId) {
+            call.resolve()
+            return
+        }
+
+        activity?.runOnUiThread {
+            overlay?.dismiss()
+            call.resolve()
+        } ?: call.resolve()
+    }
+
+    override fun handleOnDestroy() {
+        overlay?.destroy()
+        overlay = null
+        overlayActivity = null
+        currentToastId = null
+    }
+
+    private fun ensureOverlay(): ToastOverlay? {
+        val activity = activity ?: return null
+        if (overlay == null || overlayActivity !== activity) {
+            overlay?.destroy()
+            overlayActivity = activity
+            overlay = ToastOverlay(activity).apply {
+                onDismiss = {
+                    val toastId = currentToastId
+                    if (toastId != null) {
+                        notifyListeners("toastDismiss", JSObject().put("id", toastId))
+                        currentToastId = null
+                    }
+                }
+                onPress = {
+                    val toastId = currentToastId
+                    if (toastId != null) {
+                        notifyListeners("toastPress", JSObject().put("id", toastId))
+                    }
+                }
+                onActionPress = {
+                    val toastId = currentToastId
+                    if (toastId != null) {
+                        notifyListeners("toastActionPress", JSObject().put("id", toastId))
+                    }
+                }
+            }
+        }
+
+        return overlay
+    }
+
+    private fun parsePayload(call: PluginCall): ToastPayload? {
+        val id = call.getString("id")
+        if (id.isNullOrBlank()) {
+            call.reject("Missing required parameter: id")
+            return null
+        }
+
+        return ToastPayload(
+            id = id,
+            icon = call.getString("icon") ?: "",
+            iconUri = call.getString("iconUri") ?: "",
+            title = call.getString("title") ?: "",
+            message = call.getString("message") ?: "",
+            duration = call.getInt("duration") ?: 3000,
+            autoDismiss = call.getBoolean("autoDismiss") ?: true,
+            enableSwipeDismiss = call.getBoolean("enableSwipeDismiss") ?: true,
+            useDynamicIsland = call.getBoolean("useDynamicIsland") ?: true,
+            accentColor = parseColor(call.getString("accentColor")),
+            strokeColor = parseColor(call.getString("strokeColor")),
+            disableBackdropSampling = call.getBoolean("disableBackdropSampling") ?: false,
+            actionLabel = call.getString("actionLabel") ?: "",
+            accessibilityAnnouncement = call.getString("accessibilityAnnouncement") ?: "",
+        )
+    }
+
+    private fun parseColor(value: String?): Int? {
+        if (value.isNullOrBlank()) return null
+
+        return try {
+            when {
+                value.startsWith("rgb(", ignoreCase = true) -> parseRgbColor(value)
+                value.startsWith("rgba(", ignoreCase = true) -> parseRgbaColor(value)
+                else -> Color.parseColor(value)
+            }
+        } catch (_: IllegalArgumentException) {
+            null
+        }
+    }
+
+    private fun parseRgbColor(value: String): Int {
+        val content = value.substringAfter("(").substringBeforeLast(")")
+        val components = content.split(",").map { it.trim().toInt() }
+        return Color.rgb(components[0], components[1], components[2])
+    }
+
+    private fun parseRgbaColor(value: String): Int {
+        val content = value.substringAfter("(").substringBeforeLast(")")
+        val components = content.split(",").map { it.trim() }
+        val alpha = (components[3].toFloat() * 255).toInt().coerceIn(0, 255)
+        return Color.argb(alpha, components[0].toInt(), components[1].toInt(), components[2].toInt())
+    }
+}
+
+private data class ToastPayload(
+    val id: String,
+    val icon: String,
+    val iconUri: String,
+    val title: String,
+    val message: String,
+    val duration: Int,
+    val autoDismiss: Boolean,
+    val enableSwipeDismiss: Boolean,
+    val useDynamicIsland: Boolean,
+    val accentColor: Int?,
+    val strokeColor: Int?,
+    val disableBackdropSampling: Boolean,
+    val actionLabel: String,
+    val accessibilityAnnouncement: String,
+)