react-native-blur-vibe 0.1.5 → 0.1.7

package/src/types.ts

@@ -1,5 +1,44 @@
 import type { ViewProps } from 'react-native';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// BlurType
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * iOS blur material style — maps directly to `UIBlurEffect.Style`.
+ *
+ * **iOS only.** Ignored on Android (Android uses `blurAmount` + `overlayColor`
+ * to control blur appearance).
+ *
+ * ### Adaptive styles (recommended)
+ * These automatically adapt to light/dark mode:
+ * - `"light"` — light frosted glass (default)
+ * - `"dark"` — dark frosted glass
+ * - `"extraLight"` — brighter than light
+ * - `"regular"` — system default material
+ * - `"prominent"` — higher contrast than regular
+ *
+ * ### Material styles (iOS 13+, adaptive)
+ * - `"systemUltraThinMaterial"` — thinnest, most transparent
+ * - `"systemThinMaterial"` — thin
+ * - `"systemMaterial"` — medium (equivalent to iOS sheet backgrounds)
+ * - `"systemThickMaterial"` — thick
+ * - `"systemChromeMaterial"` — for toolbars and navigation bars
+ *
+ * ### Light variants (iOS 13+, always light)
+ * - `"systemUltraThinMaterialLight"`
+ * - `"systemThinMaterialLight"`
+ * - `"systemMaterialLight"`
+ * - `"systemThickMaterialLight"`
+ * - `"systemChromeMaterialLight"`
+ *
+ * ### Dark variants (iOS 13+, always dark)
+ * - `"systemUltraThinMaterialDark"`
+ * - `"systemThinMaterialDark"`
+ * - `"systemMaterialDark"`
+ * - `"systemThickMaterialDark"`
+ * - `"systemChromeMaterialDark"`
+ */
 export type BlurType =
   | 'light'
   | 'dark'
@@ -22,44 +61,254 @@ export type BlurType =
   | 'systemThickMaterialDark'
   | 'systemChromeMaterialDark';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// ProgressiveBlurDirection
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Direction for progressive (gradient) blur.
+ *
+ * Controls which axis the blur fades across, and which end starts at full
+ * intensity vs. transparent. Use with `progressiveStartIntensity` and
+ * `progressiveEndIntensity` for fine control.
+ *
+ * **iOS**: Uses `CAFilter variableBlur` — true per-pixel variable radius,
+ * same technique as Apple's Home Screen and Control Center. Falls back to
+ * `maskView` opacity gradient if CAFilter is unavailable.
+ *
+ * **Android API 31+**: Uses `LinearGradient`/`RadialGradient` as an alpha
+ * mask over the GPU `RenderEffect` blur layer.
+ *
+ * **Android API < 31**: Silently ignored (uniform blur is shown).
+ *
+ * | Value            | Blur starts at | Fades towards  |
+ * |------------------|----------------|----------------|
+ * | `"topToBottom"`  | Top edge       | Bottom edge    |
+ * | `"bottomToTop"`  | Bottom edge    | Top edge       |
+ * | `"leftToRight"`  | Left edge      | Right edge     |
+ * | `"rightToLeft"`  | Right edge     | Left edge      |
+ * | `"radial"`       | Center         | Outer edges    |
+ * | `"none"`         | — uniform blur — no gradient    |
+ *
+ * @example
+ * // Sticky header: full blur at top, invisible at bottom
+ * progressiveBlurDirection="topToBottom"
+ * progressiveStartIntensity={1}
+ * progressiveEndIntensity={0}
+ *
+ * @example
+ * // Bottom sheet scrim: invisible at top, full blur at bottom
+ * progressiveBlurDirection="bottomToTop"
+ * progressiveStartIntensity={1}
+ * progressiveEndIntensity={0}
+ */
+export type ProgressiveBlurDirection =
+  | 'topToBottom'
+  | 'bottomToTop'
+  | 'leftToRight'
+  | 'rightToLeft'
+  | 'radial'
+  | 'none';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BlurViewProps
+// ─────────────────────────────────────────────────────────────────────────────
+
 export interface BlurViewProps extends ViewProps {
+  // ─── Core props (iOS + Android) ───────────────────────────────────────────
+
   /**
-   * Blur intensity from 0 to 100.
+   * Blur intensity. Range: `0` (no blur) to `100` (maximum blur).
+   *
+   * Approximate CSS `backdrop-filter` equivalents:
+   *
+   * | `blurAmount` | CSS equivalent          | Visual feel         |
+   * |-------------|-------------------------|---------------------|
+   * | `5`         | `backdrop-blur-sm` (4px)  | Subtle hint of blur |
+   * | `15`        | `backdrop-blur` (8px)     | Light frosted glass |
+   * | `25`        | `backdrop-blur-md` (12px) | Standard card blur  |
+   * | `50`        | `backdrop-blur-xl` (24px) | Heavy frosted glass |
+   * | `75`        | `backdrop-blur-2xl`       | Dense blur          |
+   * | `100`       | `backdrop-blur-3xl`       | Maximum blur        |
+   *
+   * **iOS**: Controls `UIViewPropertyAnimator` fraction on `UIBlurEffect`.
+   * **Android API 31+**: Maps quadratically to `RenderEffect.createBlurEffect` radius (0–25px).
+   * **Android API < 31**: Maps to `RenderScript` Gaussian radius via QmBlurView.
+   *
    * @default 10
    */
   blurAmount?: number;
 
   /**
-   * iOS only — maps to UIBlurEffectStyle.
-   * @default 'light'
+   * Overlay color composited **on top of** the blur layer.
+   *
+   * Equivalent to CSS:
+   * ```css
+   * backdrop-filter: blur(Xpx);
+   * background-color: <overlayColor>;
+   * ```
+   *
+   * The alpha channel controls how much of the blur is visible:
+   * - `"#00000000"` — fully transparent, pure blur (no tint)
+   * - `"#00000040"` — 25% black tint over blur (dark frosted glass)
+   * - `"#FFFFFF30"` — 19% white tint over blur (light frosted glass)
+   * - `"#000000FF"` — fully opaque black, blur is hidden
+   *
+   * Supported color formats: `"transparent"`, `"#RGB"`, `"#RRGGBB"`, `"#RRGGBBAA"`
+   *
+   * **Works on both iOS and Android.**
+   *
+   * @default `"transparent"` on iOS, `"#00000030"` on Android
    */
-  blurType?: BlurType;
+  overlayColor?: string;
 
   /**
-   * Overlay color composited ON TOP of the blur layer. Works on iOS AND Android.
+   * Fallback solid color shown when blur effects are unavailable.
    *
-   * Alpha channel controls how much blur is visible — like CSS:
-   *   backdrop-filter: blur(Xpx) + background-color: overlayColor
+   * Shown when:
+   * - **iOS**: User has enabled *Reduce Transparency* in Accessibility settings
+   * - **Android**: Device API level < 21
    *
-   * "#00000000" → transparent overlay = pure blur
-   * "#00000080" → semi-transparent black tint over blur
-   * "#FFFFFFFF" → fully opaque = blur hidden
+   * Should be a color that provides sufficient contrast for your UI without
+   * the blur effect. Commonly a semi-opaque version of your background color.
    *
-   * @default "transparent" on iOS | "#00000030" on Android
+   * Supported formats: `"transparent"`, `"#RGB"`, `"#RRGGBB"`, `"#RRGGBBAA"`
+   *
+   * **Works on both iOS and Android.**
+   *
+   * @default `"#F2F2F2"`
    */
-  overlayColor?: string;
+  reducedTransparencyFallbackColor?: string;
+
+  // ─── iOS-only props ───────────────────────────────────────────────────────
 
   /**
-   * Fallback color when blur is unavailable.
-   * (Reduce Transparency on iOS, API < 21 on Android)
-   * @default "#F2F2F2"
+   * iOS blur material style.
+   *
+   * Maps to `UIBlurEffect.Style`. Controls the visual character of the blur —
+   * thickness, color tint, and how content shows through.
+   *
+   * Use adaptive styles (`"systemMaterial"`, `"light"`, `"dark"`) for apps
+   * that support both light and dark mode.
+   *
+   * **iOS only.** Ignored on Android — use `overlayColor` to tint the blur
+   * on Android.
+   *
+   * @default `"light"`
+   * @platform ios
    */
-  reducedTransparencyFallbackColor?: string;
+  blurType?: BlurType;
+
+  // ─── Android-only props ───────────────────────────────────────────────────
 
   /**
-   * Android only — downscale factor for RenderScript blur path (API 21-30).
-   * Higher = faster performance, slightly softer blur. Range: 1–8.
+   * Android API < 31 only — RenderScript capture downsample factor.
+   *
+   * Controls how aggressively the screen is downsampled before the blur
+   * kernel is applied. Higher values are faster but produce a softer,
+   * less detailed blur.
+   *
+   * | Value | Resolution captured | Quality  | Performance |
+   * |-------|---------------------|----------|-------------|
+   * | `1`   | Full resolution     | Sharpest | Slowest     |
+   * | `4`   | 1/16 pixels (default) | Good   | Fast        |
+   * | `8`   | 1/64 pixels         | Softer   | Fastest     |
+   *
+   * On **Android API 31+** this prop is ignored — blur runs at full
+   * resolution on the GPU via `RenderEffect`.
+   *
+   * On **iOS** this prop is ignored entirely.
+   *
    * @default 4
+   * @platform android
    */
   blurRadius?: number;
+
+  // ─── Progressive blur props (iOS + Android API 31+) ──────────────────────
+
+  /**
+   * Direction the blur fades across the view.
+   *
+   * Creates a gradient blur effect — full blur intensity at one edge,
+   * fading to no blur (or a different intensity) at the other.
+   * Commonly used for:
+   * - Sticky/floating headers (blur fades downward)
+   * - Bottom sheet scrims (blur fades upward)
+   * - Side drawers (blur fades horizontally)
+   * - Spotlight effects (radial, full blur at center)
+   *
+   * Use `progressiveStartIntensity` and `progressiveEndIntensity` to
+   * control the intensity at each end of the gradient.
+   *
+   * **iOS**: True per-pixel variable-radius blur via `CAFilter variableBlur`
+   * (same as Apple's Home Screen / Control Center). Falls back to opacity
+   * masking if CAFilter is unavailable.
+   *
+   * **Android API 31+**: Alpha mask gradient over GPU `RenderEffect` blur.
+   *
+   * **Android API < 31**: Silently ignored — uniform blur is shown.
+   *
+   * @default `"none"` (uniform blur)
+   * @platform ios, android (API 31+)
+   */
+  progressiveBlurDirection?: ProgressiveBlurDirection;
+
+  /**
+   * Blur intensity at the **start** of the gradient direction. Range: `0.0`–`1.0`.
+   *
+   * - `1.0` = full blur (at `blurAmount` intensity)
+   * - `0.0` = completely unblurred / transparent
+   *
+   * What "start" means per direction:
+   * - `"topToBottom"` → intensity at the **top** edge
+   * - `"bottomToTop"` → intensity at the **bottom** edge
+   * - `"leftToRight"` → intensity at the **left** edge
+   * - `"rightToLeft"` → intensity at the **right** edge
+   * - `"radial"` → intensity at the **center**
+   *
+   * @default 1.0
+   * @platform ios, android (API 31+)
+   */
+  progressiveStartIntensity?: number;
+
+  /**
+   * Blur intensity at the **end** of the gradient direction. Range: `0.0`–`1.0`.
+   *
+   * - `1.0` = full blur (at `blurAmount` intensity)
+   * - `0.0` = completely unblurred / transparent
+   *
+   * What "end" means per direction:
+   * - `"topToBottom"` → intensity at the **bottom** edge
+   * - `"bottomToTop"` → intensity at the **top** edge
+   * - `"leftToRight"` → intensity at the **right** edge
+   * - `"rightToLeft"` → intensity at the **left** edge
+   * - `"radial"` → intensity at the **outer edges**
+   *
+   * @default 0.0
+   * @platform ios, android (API 31+)
+   */
+  progressiveEndIntensity?: number;
+
+  /**
+   * Noise grain overlay strength — adds tactile frosted-glass texture.
+   *
+   * Overlays a subtle static noise pattern on top of the blur layer.
+   * This mimics the micro-texture of real ground glass, making digital
+   * blur feel more physical and premium.
+   *
+   * | Value  | Effect                                          |
+   * |--------|-------------------------------------------------|
+   * | `0`    | No noise — clean digital blur                   |
+   * | `0.08` | Subtle grain, barely perceptible (default)      |
+   * | `0.15` | Noticeable grain (matches Haze library default) |
+   * | `0.30` | Heavy grain — strong tactile texture            |
+   *
+   * **iOS**: Drawn as a tiled `CGImage` noise layer with `.overlay` blend mode.
+   * **Android API 31+**: Tiled `BitmapShader` drawn over the blur layer.
+   * **Android API < 31**: Silently ignored.
+   *
+   * @default 0.08
+   * @platform ios, android (API 31+)
+   */
+  noiseFactor?: number;
 }

package/android/src/main/java/com/blurvibe/BlurCaptureCoordinator.kt

@@ -1,230 +0,0 @@
-package com.blurvibe
-
-import android.graphics.Bitmap
-import android.graphics.Canvas
-import android.graphics.Color
-import android.graphics.Paint
-import android.os.Build
-import android.os.Handler
-import android.os.HandlerThread
-import android.os.Looper
-import android.renderscript.Allocation
-import android.renderscript.Element
-import android.renderscript.RenderScript
-import android.renderscript.ScriptIntrinsicBlur
-import android.view.Choreographer
-import android.view.ViewGroup
-import android.view.ViewTreeObserver
-import java.util.concurrent.CopyOnWriteArraySet
-
-/**
- * BlurCaptureCoordinator
- *
- * Singleton per root-view. Owns ONE preDrawListener, ONE bitmap capture, ONE blur pass
- * per vsync — shared across ALL BlurVibeViews that point at the same root.
- *
- * Cost: O(1) per frame regardless of how many BlurVibeViews are mounted.
- * Compare to naive per-view: O(N) per frame.
- *
- * Thread model:
- *   rootView.draw()   → main thread (Android requires this)
- *   RenderScript blur → workerThread (non-blocking)
- *   onBlurReady()     → main thread via mainHandler.post()
- */
-internal class BlurCaptureCoordinator private constructor(
-  private val rootView: ViewGroup
-) {
-
-  // registered BlurVibeViews — thread-safe, iterated on main thread
-  private val clients = CopyOnWriteArraySet<BlurVibeView>()
-
-  // bitmap pool — allocated once, reused every frame (zero GC)
-  private var captureBitmap: Bitmap? = null
-  private var scaledBitmap:  Bitmap? = null
-
-  private val capturePaint = Paint(Paint.FILTER_BITMAP_FLAG)
-
-  // worker thread for blur (keeps main thread free)
-  private val workerThread = HandlerThread("BlurVibeWorker-${System.identityHashCode(rootView)}")
-    .also { it.start() }
-  private val workerHandler  = Handler(workerThread.looper)
-  private val mainHandler    = Handler(Looper.getMainLooper())
-
-  // RenderScript state (API < 31 only, created lazily on workerThread)
-  private var rs:          RenderScript?        = null
-  private var blurScript:  ScriptIntrinsicBlur? = null
-  private var inputAlloc:  Allocation?          = null
-  private var outputAlloc: Allocation?          = null
-
-  // blur params
-  var blurRadius: Float = 8f
-    set(value) { field = value.coerceIn(1f, 25f) }
-  var downsampleFactor: Float = DOWNSAMPLE_FACTOR
-
-  // frame gate — at most one capture queued at a time
-  private var frameScheduled = false
-  private val frameCallback = Choreographer.FrameCallback {
-    frameScheduled = false
-    captureAndBlur()
-  }
-
-  // ONE preDrawListener for the entire coordinator
-  private val preDrawListener = ViewTreeObserver.OnPreDrawListener {
-    if (!frameScheduled) {
-      frameScheduled = true
-      Choreographer.getInstance().postFrameCallback(frameCallback)
-    }
-    true  // never block the draw pass
-  }
-
-  // ── Init / destroy ────────────────────────────────────────────────────────
-
-  init {
-    rootView.viewTreeObserver.addOnPreDrawListener(preDrawListener)
-    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.S) {
-      workerHandler.post { initRenderScript() }
-    }
-  }
-
-  private fun destroy() {
-    rootView.viewTreeObserver.removeOnPreDrawListener(preDrawListener)
-    Choreographer.getInstance().removeFrameCallback(frameCallback)
-    cache.remove(rootView)
-    workerHandler.post {
-      inputAlloc?.destroy();  inputAlloc  = null
-      outputAlloc?.destroy(); outputAlloc = null
-      blurScript?.destroy();  blurScript  = null
-      rs?.destroy();          rs          = null
-      captureBitmap?.recycle(); captureBitmap = null
-      scaledBitmap?.recycle();  scaledBitmap  = null
-      workerThread.quitSafely()
-    }
-  }
-
-  // ── Registration ──────────────────────────────────────────────────────────
-
-  fun register(view: BlurVibeView) {
-    clients.add(view)
-    // deliver cached result immediately so view doesn't flash blank
-    scaledBitmap?.takeIf { !it.isRecycled }?.let { view.onBlurReady(it) }
-  }
-
-  fun unregister(view: BlurVibeView) {
-    clients.remove(view)
-    if (clients.isEmpty()) destroy()
-  }
-
-  // ── Capture + blur pipeline ───────────────────────────────────────────────
-
-  private fun captureAndBlur() {
-    if (clients.isEmpty()) return
-    val w = rootView.width;  if (w <= 0) return
-    val h = rootView.height; if (h <= 0) return
-
-    val factor  = downsampleFactor
-    val scaledW = (w / factor).toInt().coerceAtLeast(1)
-    val scaledH = (h / factor).toInt().coerceAtLeast(1)
-
-    // allocate / reuse bitmaps
-    val capture = reuseBitmap(captureBitmap, w, h).also      { captureBitmap = it }
-    val scaled  = reuseBitmap(scaledBitmap, scaledW, scaledH).also { scaledBitmap  = it }
-
-    // ① capture on main thread (required by Android)
-    try {
-      val c = Canvas(capture)
-      c.drawColor(Color.TRANSPARENT, android.graphics.PorterDuff.Mode.CLEAR)
-      rootView.draw(c)
-    } catch (_: Exception) { return }
-
-    val radius        = blurRadius
-    val captureRef    = capture
-    val scaledRef     = scaled
-
-    // ② blur on worker thread
-    workerHandler.post {
-      // downsample
-      Canvas(scaledRef).drawBitmap(
-        captureRef,
-        android.graphics.Rect(0, 0, captureRef.width, captureRef.height),
-        android.graphics.Rect(0, 0, scaledRef.width,  scaledRef.height),
-        capturePaint
-      )
-
-      // blur
-      val blurred = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
-        blurSoftware(scaledRef, radius)   // BlurMaskFilter — fast enough at small size
-      } else {
-        blurRenderScript(scaledRef, radius) ?: blurSoftware(scaledRef, radius)
-      }
-
-      // ③ deliver to all clients on main thread
-      mainHandler.post {
-        clients.forEach { it.onBlurReady(blurred) }
-      }
-    }
-  }
-
-  // ── Blur implementations ──────────────────────────────────────────────────
-
-  private fun initRenderScript() {
-    try {
-      rs         = RenderScript.create(rootView.context)
-      blurScript = ScriptIntrinsicBlur.create(rs, Element.U8_4(rs))
-    } catch (_: Exception) {}
-  }
-
-  private fun blurRenderScript(src: Bitmap, radius: Float): Bitmap? {
-    val r  = this.rs          ?: return null
-    val sc = this.blurScript  ?: return null
-    return try {
-      val inA  = reuseAlloc(inputAlloc,  src, r).also { inputAlloc  = it }
-      val outA = reuseAlloc(outputAlloc, src, r).also { outputAlloc = it }
-      inA.copyFrom(src)
-      sc.setRadius(radius)
-      sc.setInput(inA)
-      sc.forEach(outA)
-      val out = Bitmap.createBitmap(src.width, src.height, Bitmap.Config.ARGB_8888)
-      outA.copyTo(out)
-      out
-    } catch (_: Exception) { null }
-  }
-
-  private fun blurSoftware(src: Bitmap, radius: Float): Bitmap {
-    val out   = Bitmap.createBitmap(src.width, src.height, Bitmap.Config.ARGB_8888)
-    val paint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
-      maskFilter = android.graphics.BlurMaskFilter(radius, android.graphics.BlurMaskFilter.Blur.NORMAL)
-    }
-    Canvas(out).drawBitmap(src, 0f, 0f, paint)
-    return out
-  }
-
-  // ── Bitmap / Allocation helpers ───────────────────────────────────────────
-
-  private fun reuseBitmap(existing: Bitmap?, w: Int, h: Int): Bitmap {
-    if (existing != null && !existing.isRecycled
-        && existing.width == w && existing.height == h) return existing
-    existing?.recycle()
-    return Bitmap.createBitmap(w, h, Bitmap.Config.ARGB_8888)
-  }
-
-  private fun reuseAlloc(existing: Allocation?, src: Bitmap, rs: RenderScript): Allocation {
-    if (existing != null
-        && existing.type.x == src.width
-        && existing.type.y == src.height) return existing
-    existing?.destroy()
-    return Allocation.createFromBitmap(rs, src,
-      Allocation.MipmapControl.MIPMAP_NONE, Allocation.USAGE_SCRIPT)
-  }
-
-  // ── Singleton cache ───────────────────────────────────────────────────────
-
-  companion object {
-    /** Global downsample factor. Higher = faster + softer. Range 2–16. */
-    var DOWNSAMPLE_FACTOR: Float = 8f
-
-    private val cache = HashMap<ViewGroup, BlurCaptureCoordinator>()
-
-    fun forRoot(rootView: ViewGroup): BlurCaptureCoordinator =
-      cache.getOrPut(rootView) { BlurCaptureCoordinator(rootView) }
-  }
-}