react-native-attachment-kit 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## Unreleased
+
+- **Viewer (iOS): a video page with no poster image now shows the video**. The player layer sits inside the page's image view, and that view only got a size from a loaded image, so with an empty poster URL or a failed poster download the layer stayed 0×0: the video played (sound, position moving) on an empty page. `ViewerVideoItemView` now sizes the area from `presentationSize` (rotation metadata included), or the page size until that is known. Once a poster arrives its size is used, as before.
+  - Checked on the iOS simulator (test harness): empty poster and 404 poster with local / remote / download-to-`cacheFile` videos, landscape, portrait and 90°-rotation-metadata files. Poster pages have the same frames as before; a poster arriving late, swiping away and back, pinch zoom, and the zoom close from the current frame all work.
+
+## 1.1.2 — 2026-11-03
+
+- **Viewer: `underlayViewTag` — the photo moves *behind* the app's translucent bar during the zoom open / close (iOS + Android `useOverlayViewer`)**. With 1.1.1's clip the moving photo was only cut at the bar, so the part under the bar was simply missing while it moved (and an app that kept its cell visible showed that part already in place). Now the app places an empty view right below the bar and passes its RN tag; the kit draws a copy of the moving photo and of the source mask inside that view: the bar's live blur shows the photo sliding under it and the source cell's under-bar part is hidden by the copied mask from the first frame until the close ends. The clipped photo in the viewer window stays as before (so it never covers the bar). The first version of this option (`closeBelowViewTag`, never published) inserted the copy into the bar's parent; that shifted React's child indexes and debug builds crashed with "Attempt to unmount a view which has a different index", so the copy now only goes inside the app's empty view.
+  - iOS: `ZoomTransitionAnimator.underView` (weak, the empty view) — under layer + copy mask (follows `updateMaskView`) + copy image animated with the same frames; removed when the close ends (zoom, fade or slide). The bridge resolves the tag with `viewWithTag` (Fabric sets component views' `tag` to the RN tag).
+  - Android: `ImageViewerOverlayView` finds the empty view by id (= RN tag) and adds a `FrameLayout` inside it, laid out by hand (RN view groups don't lay out foreign children); the copy image has `activityRoot`'s size/place so it reuses the dummy's matrix and outline each frame; the copy mask follows the mask (position, drawable, visibility). Removed in `cleanup()`.
+  - Android: the copy image also gets `clipBounds` = this frame's cell. The app's blur view captures the screen on a software canvas, where `clipToOutline` is ignored, so the whole uncut photo went into the blur and the bar turned lighter until the copy was removed at the end of the close (seen with a large single photo; iOS not affected). `clipBounds` applies in both drawing paths. Measured on an emulator, same card, dark mode, mean brightness of the title row: settled 24.1, last frames of the close 30.9 before; settled 24.6, last frames 24.7 – 24.9 after.
+  - Checked on the iOS simulator and an Android emulator (HeyTalk feed).
+
+## 1.1.1 — 2026-11-03
+
+- **Viewer: `sourceClipInsets` / `sourceClipRect` options — the zoom open / close stays behind translucent bars (iOS + Android `useOverlayViewer`)**. The moving photo and the `hideSourceImage` mask are drawn in the window above the app, so a thumbnail half under the app's translucent top bar flew back *over* the bar and the mask covered the bar too. With a clip area (screen-edge insets, a rect in `sourceRect` coordinates, or both = intersection) they are drawn only inside it: on open the photo starts cut at the bar and the clip widens to the full screen during the second half (the viewer itself is never cut); on close it narrows back in the first 20 % (the viewer background turns transparent at once on close, so the photo never covers the bar), and the part under the bar disappears behind it. Checked on the iOS simulator (HeyTalk feed): a cell half under the translucent top bar opens from behind the bar and closes back behind it; a cell clear of the bar animates as before. `updateSourceRect` takes the same keys (changed only when passed, `null` = no clip) for paging to another thumbnail. Without the options nothing changes.
+  - iOS: `ZoomTransitionAnimator.sourceClipRect` / `sourceClipInsets` (public) — the dummy image sits in a full-screen view whose `mask` view animates between the clip and the bounds; the source mask sits in a holder of the clip's size (`clipsToBounds`). Other users of the animator (gallery, media gallery) pass nothing.
+  - Android: `ImageViewerOverlayView` sets `clipBounds` on the dummy image (lerped with the open / close progress) and on the mask (its own coordinates, refreshed whenever the mask moves). Insets are measured from the window's decor view. The Activity / Dialog viewers ignore the options.
 ## 1.1.0 — 2026-10-27
 
 - **New public API for native screens: `AttachmentProcessor` (iOS framework + Android aar)** — the "after picking" processing that used to live only inside the RN bridge (photo resize and save as webp / jpg / png, photo thumbnail, video export with `VideoExporter` and its poster, the processing-start slots with predicted sizes and posters, progress throttling, per-video cancel, temp files and the result model). An app's own native screen can now open the kit gallery and process the result with exactly the same code as `openGallery`, so both produce the same files (size, thumbnail, poster).

package/README.md

@@ -341,6 +341,9 @@ ref.current?.measure((x, y, width, height, pageX, pageY) => {
 | `sourceBorderCorners` | `('topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight')[]` | Which corners are rounded (chat-bubble groups). `[]` = none. |
 | `sourceBackgroundColor` | `string` | Background behind the thumbnail during the animation. |
 | `hideSourceImage` | `boolean` | A native mask hides the source thumbnail while the viewer is open. |
+| `sourceClipInsets` | `{ top?, bottom?, left?, right? }` | Screen-edge insets of the area where the **moving photo and the `hideSourceImage` mask** are drawn during the zoom open / close (e.g. `{ top: headerHeight, bottom: tabBarHeight }` for translucent bars). A thumbnail half under a translucent bar then slides **behind** the bar instead of over it. The clip widens to the full screen in the second half of the open (when the viewer background covers the bar) and narrows in the first 20 % of the close, so the viewer itself is never cut. iOS + Android `useOverlayViewer`. |
+| `sourceClipRect` | `SourceRect` | Same, as a rect in `sourceRect` coordinates (e.g. a list area inside a sheet). With both, the intersection is used. Omit both = no clipping (as before). |
+| `underlayViewTag` | `number` | `findNodeHandle` of an **empty** view the app places right below its translucent bar: full screen, no children, `collapsable={false}`, `pointerEvents="none"`, rendered after the list and before the bar. During the zoom open / close a copy of the moving photo and of the source mask is drawn inside it, so the bar's live blur shows the photo sliding behind it — clipping alone only hides the part under the bar. Use with `sourceClipInsets` / `sourceClipRect`. Never pass a view that has React children: native views added there shift React's child indexes and the app can crash. iOS + Android `useOverlayViewer`. |
 
 **Actions**
 
@@ -368,8 +371,8 @@ ref.current?.measure((x, y, width, height, pageX, pageY) => {
 | `useDialogViewer: true` | DialogFragment — no `AppState` blip, but background RN layout changes may not render until it closes. |
 | `useOverlayViewer: true` | ⭐ View on top of the host Activity's window — no `AppState` blip, background changes render in real time. Wins over `useDialogViewer`. |
 
-#### `updateSourceRect(rect: SourceRect & { sourceBorderRadius?, sourceBorderCorners? }): Promise<void>`
-Updates where the viewer closes to (e.g. after paging to another thumbnail or scrolling).
+#### `updateSourceRect(rect: ViewerSourceUpdate): Promise<void>`
+Updates where the viewer closes to (e.g. after paging to another thumbnail or scrolling). `ViewerSourceUpdate = SourceRect & { sourceBorderRadius?, sourceBorderCorners?, sourceClipRect?, sourceClipInsets?, underlayViewTag? }` — the clip keys change only when passed (`null` = stop clipping).
 
 #### `injectImageCache(url: string, localPath: string): Promise<boolean>`
 Seeds the viewer's image cache with a local file for a remote URL, so it opens instantly without network.

package/android/src/newarch/java/com/rnattachmentkit/RNAttachmentKitModule.kt

@@ -212,12 +212,36 @@ class RNAttachmentKitModule(reactContext: ReactApplicationContext) :
             }
         }
 
+        // 잘라내기 영역 — 넘긴 키만 바뀜 (useOverlayViewer 뷰어만 반영)
+        clipArrayOf(options, "sourceClipRect")?.let { intent.putExtra("sourceClipRect", it) }
+        clipArrayOf(options, "sourceClipInsets")?.let { intent.putExtra("sourceClipInsets", it) }
+        if (options.hasKey("underlayViewTag")) {
+            intent.putExtra("underlayViewTag", if (options.isNull("underlayViewTag")) 0 else options.getDouble("underlayViewTag").toInt())
+        }
         androidx.localbroadcastmanager.content.LocalBroadcastManager.getInstance(reactApplicationContext)
             .sendBroadcast(intent)
             
         promise.resolve(null)
     }
 
+    /**
+     * sourceClipRect {x,y,width,height} / sourceClipInsets {top,bottom,left,right} (dp) → 화면 px [l,t,r,b]
+     * (여백이면 각 변의 여백). 키가 없으면 null(안 바꿈), 값이 null 이면 빈 배열(자르지 않음).
+     */
+    private fun clipArrayOf(options: ReadableMap, key: String): FloatArray? {
+        if (!options.hasKey(key)) return null
+        if (options.isNull(key)) return FloatArray(0)
+        val m = options.getMap(key) ?: return FloatArray(0)
+        fun px(k: String) = if (m.hasKey(k) && !m.isNull(k)) com.facebook.react.uimanager.PixelUtil.toPixelFromDIP(m.getDouble(k).toFloat()) else 0f
+        return if (key == "sourceClipRect") {
+            val x = px("x")
+            val y = px("y")
+            floatArrayOf(x, y, x + px("width"), y + px("height"))
+        } else {
+            floatArrayOf(px("left"), px("top"), px("right"), px("bottom"))
+        }
+    }
+
     override fun getName(): String = NAME
 
     override fun init(licenseKey: String, promise: Promise) {
@@ -664,6 +688,13 @@ class RNAttachmentKitModule(reactContext: ReactApplicationContext) :
                     if (options.hasKey("sourceBackgroundColor")) {
                         putString("sourceBackgroundColor", options.getString("sourceBackgroundColor"))
                     }
+                    // 잘라내기 영역 (열림·닫힘 중 사진과 가림 판이 그려지는 곳) — 이 오버레이 뷰어만
+                    clipArrayOf(options, "sourceClipRect")?.let { putFloatArray("sourceClipRect", it) }
+                    clipArrayOf(options, "sourceClipInsets")?.let { putFloatArray("sourceClipInsets", it) }
+                    // 앱 쪽 사본을 그릴 자리 — 앱이 둔 빈 RN 뷰 (태그 = view id)
+                    if (options.hasKey("underlayViewTag") && !options.isNull("underlayViewTag")) {
+                        putInt("underlayViewTag", options.getDouble("underlayViewTag").toInt())
+                    }
                     // placeholderImages: 타입/뷰어 코드에는 있었지만 브릿지에서 한 번도 전달되지 않았던
                     // 필드. 네이티브 뷰어가 onlyRetrieveFromCache(true)로 첫 프레임을 즉시 그리려 할 때
                     // 쓰는 저해상도 대체 이미지 목록입니다(원본 다운로드 전 임시 표시용).

package/android/src/oldarch/java/com/rnattachmentkit/RNAttachmentKitModule.kt

@@ -522,10 +522,34 @@ class RNAttachmentKitModule(reactContext: ReactApplicationContext) :
                 intent.putStringArrayListExtra("sourceBorderCorners", corners)
             }
         }
+        // 잘라내기 영역 — 넘긴 키만 바뀜 (useOverlayViewer 뷰어만 반영)
+        clipArrayOf(options, "sourceClipRect")?.let { intent.putExtra("sourceClipRect", it) }
+        clipArrayOf(options, "sourceClipInsets")?.let { intent.putExtra("sourceClipInsets", it) }
+        if (options.hasKey("underlayViewTag")) {
+            intent.putExtra("underlayViewTag", if (options.isNull("underlayViewTag")) 0 else options.getDouble("underlayViewTag").toInt())
+        }
         androidx.localbroadcastmanager.content.LocalBroadcastManager.getInstance(reactApplicationContext).sendBroadcast(intent)
         promise.resolve(null)
     }
 
+    /**
+     * sourceClipRect {x,y,width,height} / sourceClipInsets {top,bottom,left,right} (dp) → 화면 px [l,t,r,b]
+     * (여백이면 각 변의 여백). 키가 없으면 null(안 바꿈), 값이 null 이면 빈 배열(자르지 않음).
+     */
+    private fun clipArrayOf(options: ReadableMap, key: String): FloatArray? {
+        if (!options.hasKey(key)) return null
+        if (options.isNull(key)) return FloatArray(0)
+        val m = options.getMap(key) ?: return FloatArray(0)
+        fun px(k: String) = if (m.hasKey(k) && !m.isNull(k)) com.facebook.react.uimanager.PixelUtil.toPixelFromDIP(m.getDouble(k).toFloat()) else 0f
+        return if (key == "sourceClipRect") {
+            val x = px("x")
+            val y = px("y")
+            floatArrayOf(x, y, x + px("width"), y + px("height"))
+        } else {
+            floatArrayOf(px("left"), px("top"), px("right"), px("bottom"))
+        }
+    }
+
     /** 동영상 변환 취소 (HUD 없이 앱이 말풍선에서). index -1 = 남은 동영상 전부. 진행 중인 처리가 없으면 false */
     @ReactMethod
     fun cancelVideoProcessing(index: Double, processingId: String, promise: Promise) {
@@ -673,6 +697,13 @@ class RNAttachmentKitModule(reactContext: ReactApplicationContext) :
                     if (options.hasKey("sourceBackgroundColor")) {
                         putString("sourceBackgroundColor", options.getString("sourceBackgroundColor"))
                     }
+                    // 잘라내기 영역 (열림·닫힘 중 사진과 가림 판이 그려지는 곳) — 이 오버레이 뷰어만
+                    clipArrayOf(options, "sourceClipRect")?.let { putFloatArray("sourceClipRect", it) }
+                    clipArrayOf(options, "sourceClipInsets")?.let { putFloatArray("sourceClipInsets", it) }
+                    // 앱 쪽 사본을 그릴 자리 — 앱이 둔 빈 RN 뷰 (태그 = view id)
+                    if (options.hasKey("underlayViewTag") && !options.isNull("underlayViewTag")) {
+                        putInt("underlayViewTag", options.getDouble("underlayViewTag").toInt())
+                    }
                     // placeholderImages: 타입/뷰어 코드에는 있었지만 브릿지에서 한 번도 전달되지 않았던
                     // 필드. 네이티브 뷰어가 onlyRetrieveFromCache(true)로 첫 프레임을 즉시 그리려 할 때
                     // 쓰는 저해상도 대체 이미지 목록입니다(원본 다운로드 전 임시 표시용).

package/ios/RNAttachmentKit.swift

@@ -175,6 +175,16 @@ class RNAttachmentKit: RCTEventEmitter {
                 } else if let r = optDict["sourceBorderRadius"] as? Double {
                     self.zoomAnimator.sourceBorderRadius = CGFloat(r)
                 }
+                // 잘라내기 영역 — 키가 있을 때만 바꿈 (null = 자르지 않음)
+                if optDict.keys.contains("sourceClipRect") {
+                    self.zoomAnimator.sourceClipRect = RNAttachmentKit.parseRect(optDict["sourceClipRect"])
+                }
+                if optDict.keys.contains("sourceClipInsets") {
+                    self.zoomAnimator.sourceClipInsets = RNAttachmentKit.parseInsets(optDict["sourceClipInsets"])
+                }
+                if optDict.keys.contains("underlayViewTag") {
+                    self.zoomAnimator.underView = RNAttachmentKit.viewForTag(optDict["underlayViewTag"])
+                }
                 self.zoomAnimator.updateMaskView()
                 
                 resolve(true)
@@ -203,6 +213,26 @@ class RNAttachmentKit: RCTEventEmitter {
         return CGRect(x: x, y: y, width: w, height: h)
     }
 
+    /// RN 뷰 태그(findNodeHandle) → 앱 창의 네이티브 뷰. Fabric 은 컴포넌트 뷰의 tag 에 RN 태그를 넣음. 없으면 nil (메인 스레드)
+    private static func viewForTag(_ v: Any?) -> UIView? {
+        guard let n = v as? NSNumber, n.intValue > 0 else { return nil }
+        let tag = n.intValue
+        for scene in UIApplication.shared.connectedScenes {
+            guard let ws = scene as? UIWindowScene else { continue }
+            for w in ws.windows {
+                if let found = w.viewWithTag(tag) { return found }
+            }
+        }
+        return nil
+    }
+
+    /// { top, bottom, left, right } (빠진 값 0). 객체가 아니면 nil
+    private static func parseInsets(_ v: Any?) -> UIEdgeInsets? {
+        guard let d = v as? NSDictionary else { return nil }
+        return UIEdgeInsets(top: cgFloat(d["top"]) ?? 0, left: cgFloat(d["left"]) ?? 0,
+                            bottom: cgFloat(d["bottom"]) ?? 0, right: cgFloat(d["right"]) ?? 0)
+    }
+
     /// 말풍선 이미지(정적 지도 스냅샷) 로드. 메모리/디스크 캐시 → file:// → 다운로드 순.
     /// 실패하거나 너무 오래 걸리면 nil (이미지 없이 지도만 엶)
     /// completion(이미지, 마커 뺀 이미지인지). renderLocationThumbnail 결과면 마커 뺀 짝을 씀 → 뷰어가 마커를 따로 그려
@@ -495,6 +525,9 @@ class RNAttachmentKit: RCTEventEmitter {
             parsedRect = CGRect(x: x, y: y, width: w, height: h)
         }
         
+        let sourceClipRect = RNAttachmentKit.parseRect(options["sourceClipRect"])
+        let sourceClipInsets = RNAttachmentKit.parseInsets(options["sourceClipInsets"])
+
         var sourceBorderRadius: CGFloat = 0
         if let radiusNum = options["sourceBorderRadius"] as? NSNumber {
             sourceBorderRadius = CGFloat(truncating: radiusNum)
@@ -551,6 +584,10 @@ class RNAttachmentKit: RCTEventEmitter {
             self.zoomAnimator.sourceBorderRadius = sourceBorderRadius
             self.zoomAnimator.sourceBorderCorners = mask
             self.zoomAnimator.sourceBackgroundColor = sourceBackgroundColor
+            // 애니메이터는 재사용되므로 이번 호출 값으로 덮어씀 (안 주면 자르지 않음)
+            self.zoomAnimator.sourceClipRect = sourceClipRect
+            self.zoomAnimator.sourceClipInsets = sourceClipInsets
+            self.zoomAnimator.underView = RNAttachmentKit.viewForTag(options["underlayViewTag"])
             // Reset any sourceImage left over from a previous openViewer() call - it's only
             // meant to carry this call's local placeholder (see below), and must not leak
             // into a later call that has no placeholder of its own.

package/ios/RNAttachmentKit.xcframework/Info.plist

@@ -8,32 +8,32 @@
 			<key>BinaryPath</key>
 			<string>RNAttachmentKit.framework/RNAttachmentKit</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64_x86_64-simulator</string>
+			<string>ios-arm64</string>
 			<key>LibraryPath</key>
 			<string>RNAttachmentKit.framework</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
-				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
-			<key>SupportedPlatformVariant</key>
-			<string>simulator</string>
 		</dict>
 		<dict>
 			<key>BinaryPath</key>
 			<string>RNAttachmentKit.framework/RNAttachmentKit</string>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64</string>
+			<string>ios-arm64_x86_64-simulator</string>
 			<key>LibraryPath</key>
 			<string>RNAttachmentKit.framework</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
+				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
 		</dict>
 	</array>
 	<key>CFBundlePackageType</key>