react-native-gradient-mask 0.1.0-beta.1

package/.eslintrc.js

@@ -0,0 +1,5 @@
+module.exports = {
+  root: true,
+  extends: ['universe/native', 'universe/web'],
+  ignorePatterns: ['build'],
+};

package/PUBLISHING.md

@@ -0,0 +1,171 @@
+# 發佈流程指南
+
+本文件說明如何進行 NPM 套件的測試發佈與正式發佈。
+
+## 分支策略
+
+| 分支 | 用途 | NPM 發佈 |
+|------|------|----------|
+| `main` | 正式穩定版本 | ✅ 正式發佈 |
+| `feat/*` | 功能開發 | ❌ 不發佈 |
+| `beta` | 測試版本 | ✅ Beta 發佈 |
+
+---
+
+## 測試發佈流程（非正式）
+
+### 方法一：使用 npm pack 本地測試
+
+這是最安全的方式，不會發佈到 npm registry。
+
+```bash
+# 1. 確保程式碼已建置
+npm run build
+
+# 2. 產生 .tgz 壓縮包（模擬發佈）
+npm pack
+
+# 3. 檢視產生的檔案內容
+tar -tzf react-native-gradient-mask-0.1.0.tgz
+
+# 4. 在其他專案中測試安裝
+cd /path/to/your/test-project
+npm install /path/to/react-native-gradient-mask-0.1.0.tgz
+```
+
+### 方法二：使用 npm link 本地連結
+
+適合開發階段快速測試。
+
+```bash
+# 在套件目錄
+npm run build
+npm link
+
+# 在測試專案目錄
+npm link react-native-gradient-mask
+```
+
+### 方法三：發佈 Beta 版本到 npm
+
+當需要讓其他人測試時使用。
+
+```bash
+# 1. 建置
+npm run build
+
+# 2. 更新版本號為 beta
+npm version prerelease --preid=beta
+# 例如：0.1.0 → 0.1.1-beta.0
+
+# 3. 發佈到 npm（使用 beta tag）
+npm publish --tag beta
+
+# 4. 其他人安裝 beta 版
+npm install react-native-gradient-mask@beta
+```
+
+### 方法四：使用 GitHub 作為 npm 來源
+
+直接從 GitHub 分支安裝，適合內部測試。
+
+```bash
+# 從特定分支安裝
+npm install CS6/react-native-gradient-mask#feat/add-mask
+
+# 或使用完整 URL
+npm install git+https://github.com/CS6/react-native-gradient-mask.git#feat/add-mask
+```
+
+---
+
+## 正式發佈流程
+
+### 準備工作
+
+1. **確保在 main 分支**
+   ```bash
+   git checkout main
+   git pull origin main
+   ```
+
+2. **合併功能分支**
+   ```bash
+   git merge feat/add-mask
+   ```
+
+3. **確認程式碼品質**
+   ```bash
+   npm run lint
+   npm run test
+   npm run build
+   ```
+
+4. **確認 .npmignore 排除不需要的檔案**
+   ```bash
+   npm pack --dry-run
+   ```
+
+### 發佈步驟
+
+```bash
+# 1. 更新版本號
+npm version patch   # 0.1.0 → 0.1.1（修復）
+npm version minor   # 0.1.0 → 0.2.0（新功能）
+npm version major   # 0.1.0 → 1.0.0（重大變更）
+
+# 2. 推送到 GitHub（包含 tag）
+git push origin main --tags
+
+# 3. 發佈到 npm
+npm publish
+
+# 4. 在 GitHub 建立 Release
+gh release create v0.1.1 --generate-notes
+```
+
+---
+
+## 發佈前檢查清單
+
+- [ ] 程式碼已建置 (`npm run build`)
+- [ ] 測試通過 (`npm run test`)
+- [ ] Lint 檢查通過 (`npm run lint`)
+- [ ] README.md 已更新
+- [ ] package.json 版本號正確
+- [ ] CHANGELOG.md 已更新（如有）
+- [ ] 所有相依套件版本正確
+- [ ] .npmignore 排除不必要檔案
+- [ ] 在測試專案中驗證安裝
+
+---
+
+## 常用指令速查
+
+```bash
+# 檢視將要發佈的檔案
+npm pack --dry-run
+
+# 檢視目前版本
+npm version
+
+# 檢視 npm 上的版本
+npm view react-native-gradient-mask versions
+
+# 撤銷發佈（24小時內）
+npm unpublish react-native-gradient-mask@0.1.0
+
+# 廢棄版本（不撤銷，但標記為不建議使用）
+npm deprecate react-native-gradient-mask@0.1.0 "此版本有問題，請升級"
+```
+
+---
+
+## 版本號規則（Semantic Versioning）
+
+| 變更類型 | 版本號變更 | 範例 |
+|----------|-----------|------|
+| 修復 Bug | PATCH | 0.1.0 → 0.1.1 |
+| 新增功能（向下相容） | MINOR | 0.1.0 → 0.2.0 |
+| 重大變更（不向下相容） | MAJOR | 0.1.0 → 1.0.0 |
+| 測試版 | PRERELEASE | 0.1.0 → 0.1.1-beta.0 |

package/README.md

@@ -0,0 +1,360 @@
+# react-native-gradient-mask
+
+React Native 原生漸層遮罩元件，支援 Reanimated 動畫。適用於建立淡入淡出效果、列表遮罩等視覺效果。
+
+## 特色
+
+- **跨平台支援**：iOS、Android、Web 三平台完整支援
+- **原生效能**：iOS 使用 `CAGradientLayer`，Android 使用 `Bitmap` + `PorterDuff`，Web 使用 CSS `mask-image`
+- **支援 Reanimated**：透過 `AnimatedGradientMaskView` 實現流暢的遮罩動畫
+- **彈性設定**：自訂顏色、位置、方向與遮罩強度
+- **TypeScript 支援**：完整的型別定義
+
+## 安裝
+
+```bash
+npm install react-native-gradient-mask
+# 或
+yarn add react-native-gradient-mask
+```
+
+### 前置需求
+
+- Expo SDK 50+
+- React Native 0.73+
+- react-native-reanimated >= 3.0.0（如需使用 AnimatedGradientMaskView）
+
+### iOS 設定
+
+```bash
+cd ios && pod install
+```
+
+### Android 設定
+
+無需額外設定，自動連結。
+
+---
+
+## API 參考
+
+### 匯出項目
+
+| 名稱 | 類型 | 說明 |
+|------|------|------|
+| `GradientMaskView` | Component | 基礎漸層遮罩元件 |
+| `AnimatedGradientMaskView` | Component | 支援 Reanimated 動畫的漸層遮罩元件 |
+| `GradientMaskViewProps` | Type | GradientMaskView 的 Props 型別定義 |
+| `AnimatedGradientMaskViewProps` | Type | AnimatedGradientMaskView 的 Props 型別定義 |
+
+### GradientMaskView Props
+
+| 屬性 | 型別 | 必填 | 預設值 | 說明 |
+|------|------|:----:|--------|------|
+| `colors` | `(number \| null)[]` | ✅ | - | 漸層顏色陣列，需使用 `processColor()` 處理 |
+| `locations` | `number[]` | ✅ | - | 每個顏色的位置 (0-1) |
+| `direction` | `'top' \| 'bottom' \| 'left' \| 'right'` | | `'top'` | 漸層方向 |
+| `maskOpacity` | `number` | | `1` | 遮罩效果強度 (0-1) |
+| `style` | `StyleProp<ViewStyle>` | | - | 元件樣式 |
+| `children` | `React.ReactNode` | | - | 子元件 |
+
+### AnimatedGradientMaskView Props
+
+| 屬性 | 型別 | 必填 | 預設值 | 說明 |
+|------|------|:----:|--------|------|
+| `colors` | `(number \| null)[]` | ✅ | - | 同 GradientMaskView |
+| `locations` | `number[]` | ✅ | - | 同 GradientMaskView |
+| `direction` | `'top' \| 'bottom' \| 'left' \| 'right'` | | `'top'` | 同 GradientMaskView |
+| `maskOpacity` | `SharedValue<number>` | ✅ | - | Reanimated SharedValue，用於動畫控制 |
+| `style` | `StyleProp<ViewStyle>` | | - | 元件樣式 |
+| `children` | `React.ReactNode` | | - | 子元件 |
+
+### 方向說明
+
+| 值 | 效果 |
+|------|------|
+| `'top'` | 頂部透明，底部不透明（預設） |
+| `'bottom'` | 底部透明，頂部不透明 |
+| `'left'` | 左側透明，右側不透明 |
+| `'right'` | 右側透明，左側不透明 |
+
+### 平台支援
+
+| 平台 | 支援狀態 | 說明 |
+|------|:--------:|------|
+| iOS | ✅ | 使用 CAGradientLayer 原生實作 |
+| Android | ✅ | 使用 Bitmap + LinearGradient 實作 |
+| Web | ✅ | 使用 CSS mask-image + linear-gradient 實作 |
+
+---
+
+## 使用範例
+
+### 基本用法
+
+```tsx
+import { processColor } from 'react-native';
+import { GradientMaskView } from 'react-native-gradient-mask';
+
+// 定義漸層顏色（從透明到不透明）
+const colors = [
+  'rgba(0, 0, 0, 0)',    // 完全透明
+  'rgba(0, 0, 0, 0.5)',  // 半透明
+  'rgba(0, 0, 0, 1)',    // 完全不透明
+];
+
+// 使用 processColor 處理顏色
+const processedColors = colors.map(c => processColor(c));
+
+// 定義每個顏色的位置
+const locations = [0, 0.3, 1];
+
+function MyComponent() {
+  return (
+    <GradientMaskView
+      colors={processedColors}
+      locations={locations}
+      direction="top"
+      maskOpacity={1}
+      style={{ flex: 1 }}
+    >
+      {/* 你的內容 */}
+      <ScrollView>
+        <Text>這裡的內容會套用漸層遮罩效果</Text>
+      </ScrollView>
+    </GradientMaskView>
+  );
+}
+```
+
+### 搭配 Reanimated 動畫
+
+```tsx
+import { processColor } from 'react-native';
+import { AnimatedGradientMaskView } from 'react-native-gradient-mask';
+import {
+  useSharedValue,
+  withTiming,
+  Easing,
+} from 'react-native-reanimated';
+
+function AnimatedMaskExample() {
+  // 建立動畫 SharedValue
+  const maskOpacity = useSharedValue(0);
+
+  const colors = [
+    'rgba(0, 0, 0, 0)',
+    'rgba(0, 0, 0, 1)',
+  ].map(c => processColor(c));
+
+  const locations = [0, 1];
+
+  // 顯示遮罩效果
+  const showMask = () => {
+    maskOpacity.value = withTiming(1, {
+      duration: 600,
+      easing: Easing.in(Easing.quad),
+    });
+  };
+
+  // 隱藏遮罩效果
+  const hideMask = () => {
+    maskOpacity.value = withTiming(0, {
+      duration: 400,
+      easing: Easing.out(Easing.quad),
+    });
+  };
+
+  return (
+    <AnimatedGradientMaskView
+      colors={colors}
+      locations={locations}
+      direction="top"
+      maskOpacity={maskOpacity}
+      style={{ flex: 1 }}
+    >
+      <YourContent />
+    </AnimatedGradientMaskView>
+  );
+}
+```
+
+### 實際應用：聊天列表淡出效果
+
+```tsx
+import { useMemo, useCallback, useRef } from 'react';
+import { processColor, NativeSyntheticEvent, NativeScrollEvent } from 'react-native';
+import { FlashList } from '@shopify/flash-list';
+import { AnimatedGradientMaskView } from 'react-native-gradient-mask';
+import {
+  useSharedValue,
+  withTiming,
+  cancelAnimation,
+  Easing,
+} from 'react-native-reanimated';
+
+function ChatListWithMask({ messages }) {
+  const maskOpacity = useSharedValue(0);
+  const isAtBottomRef = useRef(false);
+
+  // 定義漸層顏色
+  const maskColors = useMemo(() => {
+    return [
+      'rgba(0,0,0,0)',
+      'rgba(0,0,0,0)',
+      'rgba(0,0,0,0.2)',
+      'rgba(0,0,0,0.6)',
+      'rgba(0,0,0,0.9)',
+      'rgba(0,0,0,1)',
+    ].map(c => processColor(c));
+  }, []);
+
+  const maskLocations = useMemo(() => [0, 0.42, 0.45, 0.48, 0.5, 1], []);
+
+  // 偵測滾動位置，動態控制遮罩
+  const handleScroll = useCallback((e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    const { contentOffset, layoutMeasurement, contentSize } = e.nativeEvent;
+    const distanceFromBottom = contentSize.height - contentOffset.y - layoutMeasurement.height;
+
+    const isAtBottom = distanceFromBottom <= 30;
+
+    if (isAtBottom !== isAtBottomRef.current) {
+      isAtBottomRef.current = isAtBottom;
+      cancelAnimation(maskOpacity);
+
+      if (isAtBottom) {
+        // 滾動到底部時顯示遮罩
+        maskOpacity.value = withTiming(1, {
+          duration: 600,
+          easing: Easing.in(Easing.quad),
+        });
+      } else {
+        // 離開底部時隱藏遮罩
+        maskOpacity.value = withTiming(0, {
+          duration: 400,
+          easing: Easing.out(Easing.quad),
+        });
+      }
+    }
+  }, []);
+
+  return (
+    <AnimatedGradientMaskView
+      colors={maskColors}
+      locations={maskLocations}
+      direction="top"
+      maskOpacity={maskOpacity}
+      style={{ flex: 1 }}
+    >
+      <FlashList
+        data={messages}
+        renderItem={({ item }) => <MessageItem item={item} />}
+        onScroll={handleScroll}
+        scrollEventThrottle={16}
+      />
+    </AnimatedGradientMaskView>
+  );
+}
+```
+
+### 不同方向的遮罩
+
+```tsx
+// 頂部淡出（預設）
+<GradientMaskView direction="top" {...props}>
+  {children}
+</GradientMaskView>
+
+// 底部淡出
+<GradientMaskView direction="bottom" {...props}>
+  {children}
+</GradientMaskView>
+
+// 左側淡出
+<GradientMaskView direction="left" {...props}>
+  {children}
+</GradientMaskView>
+
+// 右側淡出
+<GradientMaskView direction="right" {...props}>
+  {children}
+</GradientMaskView>
+```
+
+### 控制遮罩強度
+
+```tsx
+// maskOpacity = 0：無遮罩效果，內容完全可見
+<GradientMaskView maskOpacity={0} {...props}>
+  {children}
+</GradientMaskView>
+
+// maskOpacity = 0.5：半透明遮罩效果
+<GradientMaskView maskOpacity={0.5} {...props}>
+  {children}
+</GradientMaskView>
+
+// maskOpacity = 1：完整遮罩效果（預設）
+<GradientMaskView maskOpacity={1} {...props}>
+  {children}
+</GradientMaskView>
+```
+
+---
+
+## 進階技巧
+
+### 顏色處理
+
+顏色必須使用 React Native 的 `processColor()` 函式處理：
+
+```tsx
+import { processColor } from 'react-native';
+
+// ✅ 正確做法
+const colors = [
+  processColor('rgba(0, 0, 0, 0)'),
+  processColor('rgba(0, 0, 0, 1)'),
+];
+
+// ❌ 錯誤做法（不會正常運作）
+const colors = [
+  'rgba(0, 0, 0, 0)',
+  'rgba(0, 0, 0, 1)',
+];
+```
+
+### 使用 useMemo 優化效能
+
+```tsx
+const maskColors = useMemo(() => {
+  return [
+    'rgba(0,0,0,0)',
+    'rgba(0,0,0,1)',
+  ].map(c => processColor(c));
+}, []); // 只計算一次
+
+const maskLocations = useMemo(() => [0, 1], []);
+```
+
+### 避免閃爍
+
+使用 `AnimatedGradientMaskView` 搭配 `cancelAnimation` 可以避免快速切換時的閃爍問題：
+
+```tsx
+import { cancelAnimation } from 'react-native-reanimated';
+
+// 在改變動畫前先取消之前的動畫
+cancelAnimation(maskOpacity);
+maskOpacity.value = withTiming(newValue, { duration: 300 });
+```
+
+---
+
+## 授權
+
+MIT License
+
+## 作者
+
+DaYuan Lin (CS6)

package/android/build.gradle

@@ -0,0 +1,43 @@
+apply plugin: 'com.android.library'
+
+group = 'expo.modules.gradientmask'
+version = '0.1.0'
+
+def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+apply from: expoModulesCorePlugin
+applyKotlinExpoModulesCorePlugin()
+useCoreDependencies()
+useExpoPublishing()
+
+// If you want to use the managed Android SDK versions from expo-modules-core, set this to true.
+// The Android SDK versions will be bumped from time to time in SDK releases and may introduce breaking changes in your module code.
+// Most of the time, you may like to manage the Android SDK versions yourself.
+def useManagedAndroidSdkVersions = false
+if (useManagedAndroidSdkVersions) {
+  useDefaultAndroidSdkVersions()
+} else {
+  buildscript {
+    // Simple helper that allows the root project to override versions declared by this library.
+    ext.safeExtGet = { prop, fallback ->
+      rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+    }
+  }
+  project.android {
+    compileSdkVersion safeExtGet("compileSdkVersion", 36)
+    defaultConfig {
+      minSdkVersion safeExtGet("minSdkVersion", 24)
+      targetSdkVersion safeExtGet("targetSdkVersion", 36)
+    }
+  }
+}
+
+android {
+  namespace "expo.modules.gradientmask"
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.0"
+  }
+  lintOptions {
+    abortOnError false
+  }
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest>
+</manifest>

package/android/src/main/java/expo/modules/gradientmask/GradientMaskModule.kt

@@ -0,0 +1,33 @@
+package expo.modules.gradientmask
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class GradientMaskModule : Module() {
+    override fun definition() = ModuleDefinition {
+        Name("GradientMask")
+
+        // View definition
+        View(GradientMaskView::class) {
+            // colors: List of processed colors (from processColor in JS)
+            Prop("colors") { view: GradientMaskView, colors: List<Int>? ->
+                view.setColors(colors)
+            }
+
+            // locations: Array of floats (0-1) for gradient stops
+            Prop("locations") { view: GradientMaskView, locations: List<Double>? ->
+                view.setLocations(locations)
+            }
+
+            // direction: "top" | "bottom" | "left" | "right"
+            Prop("direction") { view: GradientMaskView, direction: String? ->
+                view.setDirection(direction ?: "top")
+            }
+
+            // maskOpacity: 0 = no mask effect, 1 = full gradient mask
+            Prop("maskOpacity") { view: GradientMaskView, opacity: Double? ->
+                view.setMaskOpacity(opacity ?: 1.0)
+            }
+        }
+    }
+}