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

package/src/AnimatedGradientMaskView.tsx

@@ -0,0 +1,60 @@
+import { requireNativeView } from 'expo';
+import * as React from 'react';
+import { useAnimatedProps } from 'react-native-reanimated';
+import type { SharedValue } from 'react-native-reanimated';
+import Animated from 'react-native-reanimated';
+
+import { GradientMaskViewProps } from './GradientMask.types';
+
+const NativeView: React.ComponentType<GradientMaskViewProps> =
+  requireNativeView('GradientMask');
+
+const AnimatedNativeView = Animated.createAnimatedComponent(NativeView);
+
+export type AnimatedGradientMaskViewProps = Omit<
+  GradientMaskViewProps,
+  'maskOpacity'
+> & {
+  /**
+   * Mask effect intensity (0-1) as a Reanimated SharedValue
+   * 0 = no gradient effect (content fully visible)
+   * 1 = full gradient effect
+   */
+  maskOpacity: SharedValue<number>;
+};
+
+/**
+ * AnimatedGradientMaskView - 支援 Reanimated SharedValue 動畫的漸層遮罩元件
+ *
+ * 使用方式：
+ * ```tsx
+ * const maskOpacity = useSharedValue(0);
+ *
+ * // 動畫顯示
+ * maskOpacity.value = withTiming(1, {
+ *   duration: 600,
+ *   easing: Easing.in(Easing.quad),
+ * });
+ *
+ * <AnimatedGradientMaskView
+ *   colors={colors}
+ *   locations={locations}
+ *   direction="top"
+ *   maskOpacity={maskOpacity}
+ * >
+ *   <FlashList ... />
+ * </AnimatedGradientMaskView>
+ * ```
+ */
+export default function AnimatedGradientMaskView(
+  props: AnimatedGradientMaskViewProps
+) {
+  const { maskOpacity, ...restProps } = props;
+
+  const animatedProps = useAnimatedProps<Pick<GradientMaskViewProps, 'maskOpacity'>>(() => ({
+    maskOpacity: maskOpacity.value,
+  }));
+
+  return <AnimatedNativeView {...restProps} animatedProps={animatedProps} />;
+}
+

package/src/AnimatedGradientMaskView.web.tsx

@@ -0,0 +1,149 @@
+import * as React from 'react';
+import { View, StyleSheet } from 'react-native';
+import { useAnimatedReaction, runOnJS } from 'react-native-reanimated';
+import type { SharedValue } from 'react-native-reanimated';
+
+import { GradientMaskViewProps } from './GradientMask.types';
+
+export type AnimatedGradientMaskViewProps = Omit<
+  GradientMaskViewProps,
+  'maskOpacity'
+> & {
+  /**
+   * Mask effect intensity (0-1) as a Reanimated SharedValue
+   * 0 = no gradient effect (content fully visible)
+   * 1 = full gradient effect
+   */
+  maskOpacity: SharedValue<number>;
+};
+
+/**
+ * 將 processColor 處理過的顏色值轉回 rgba 字串
+ */
+function colorToRgba(color: number | null): string {
+  if (color === null || color === undefined) {
+    return 'rgba(0, 0, 0, 0)';
+  }
+
+  const intValue = color >>> 0;
+  const a = ((intValue >> 24) & 0xff) / 255;
+  const r = (intValue >> 16) & 0xff;
+  const g = (intValue >> 8) & 0xff;
+  const b = intValue & 0xff;
+
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+/**
+ * 根據 direction 取得 CSS linear-gradient 的方向
+ */
+function getGradientDirection(direction: GradientMaskViewProps['direction']): string {
+  switch (direction) {
+    case 'top':
+      return 'to bottom';
+    case 'bottom':
+      return 'to top';
+    case 'left':
+      return 'to right';
+    case 'right':
+      return 'to left';
+    default:
+      return 'to bottom';
+  }
+}
+
+/**
+ * 建立 CSS linear-gradient 字串
+ */
+function buildGradientString(
+  colors: (number | null)[],
+  locations: number[],
+  direction: GradientMaskViewProps['direction']
+): string {
+  const gradientDirection = getGradientDirection(direction);
+
+  const colorStops = colors.map((color, index) => {
+    const rgba = colorToRgba(color);
+    const location = locations[index] !== undefined ? locations[index] * 100 : (index / (colors.length - 1)) * 100;
+    return `${rgba} ${location}%`;
+  });
+
+  return `linear-gradient(${gradientDirection}, ${colorStops.join(', ')})`;
+}
+
+/**
+ * 根據 maskOpacity 調整顏色的 alpha 值
+ */
+function adjustColorsForOpacity(
+  colors: (number | null)[],
+  maskOpacity: number
+): (number | null)[] {
+  if (maskOpacity >= 1) return colors;
+  if (maskOpacity <= 0) {
+    return colors.map(() => 0xff000000);
+  }
+
+  return colors.map((color) => {
+    if (color === null || color === undefined) return color;
+    const intValue = color >>> 0;
+    const a = ((intValue >> 24) & 0xff) / 255;
+    const r = (intValue >> 16) & 0xff;
+    const g = (intValue >> 8) & 0xff;
+    const b = intValue & 0xff;
+    const adjustedAlpha = a + (1 - a) * (1 - maskOpacity);
+    return ((Math.round(adjustedAlpha * 255) << 24) | (r << 16) | (g << 8) | b) >>> 0;
+  });
+}
+
+/**
+ * AnimatedGradientMaskView - Web 實作
+ * 使用 CSS mask-image 搭配 useAnimatedReaction 監聽 SharedValue 變化
+ */
+export default function AnimatedGradientMaskView(props: AnimatedGradientMaskViewProps) {
+  const {
+    colors,
+    locations,
+    direction = 'top',
+    maskOpacity,
+    style,
+    children,
+  } = props;
+
+  const [currentOpacity, setCurrentOpacity] = React.useState(maskOpacity.value);
+
+  // 監聽 SharedValue 變化並更新 state
+  useAnimatedReaction(
+    () => maskOpacity.value,
+    (value) => {
+      runOnJS(setCurrentOpacity)(value);
+    },
+    [maskOpacity]
+  );
+
+  const maskStyle = React.useMemo(() => {
+    if (currentOpacity <= 0) {
+      return {};
+    }
+
+    const adjustedColors = adjustColorsForOpacity(colors, currentOpacity);
+    const gradientString = buildGradientString(adjustedColors, locations, direction);
+
+    return {
+      WebkitMaskImage: gradientString,
+      maskImage: gradientString,
+      transition: 'mask-image 0.1s ease-out, -webkit-mask-image 0.1s ease-out',
+    };
+  }, [colors, locations, direction, currentOpacity]);
+
+  return (
+    <View style={[styles.container, style, maskStyle as any]}>
+      {children}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    overflow: 'hidden',
+  },
+});

package/src/GradientMask.types.ts

@@ -0,0 +1,43 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export type GradientMaskViewProps = {
+  /**
+   * Gradient colors array (processed colors from processColor)
+   * Use alpha values to control opacity
+   * e.g., ['rgba(0,0,0,0)', 'rgba(0,0,0,1)'] = transparent to opaque
+   */
+  colors: (number | null)[];
+
+  /**
+   * Position of each color (0-1)
+   * e.g., [0, 0.3, 1] means first color at 0%, second at 30%, third at 100%
+   */
+  locations: number[];
+
+  /**
+   * Gradient direction
+   * 'top' = top transparent, bottom opaque
+   * 'bottom' = bottom transparent, top opaque
+   * 'left' = left transparent, right opaque
+   * 'right' = right transparent, left opaque
+   */
+  direction?: 'top' | 'bottom' | 'left' | 'right';
+
+  /**
+   * Mask effect intensity (0-1)
+   * 0 = no gradient effect (content fully visible)
+   * 1 = full gradient effect
+   * @default 1
+   */
+  maskOpacity?: number;
+
+  /**
+   * Style
+   */
+  style?: StyleProp<ViewStyle>;
+
+  /**
+   * Children
+   */
+  children?: React.ReactNode;
+};

package/src/GradientMaskModule.ts

@@ -0,0 +1,4 @@
+import { requireNativeModule } from 'expo';
+
+// We only use the View, no module functions needed
+export default requireNativeModule('GradientMask');

package/src/GradientMaskModule.web.ts

@@ -0,0 +1,2 @@
+// Web module stub - GradientMask is primarily for native platforms
+export default {};

package/src/GradientMaskView.tsx

@@ -0,0 +1,11 @@
+import { requireNativeView } from 'expo';
+import * as React from 'react';
+
+import { GradientMaskViewProps } from './GradientMask.types';
+
+const NativeView: React.ComponentType<GradientMaskViewProps> =
+  requireNativeView('GradientMask');
+
+export default function GradientMaskView(props: GradientMaskViewProps) {
+  return <NativeView {...props} />;
+}

package/src/GradientMaskView.web.tsx

@@ -0,0 +1,129 @@
+import * as React from 'react';
+import { View, StyleSheet } from 'react-native';
+
+import { GradientMaskViewProps } from './GradientMask.types';
+
+/**
+ * 將 processColor 處理過的顏色值轉回 rgba 字串
+ */
+function colorToRgba(color: number | null): string {
+  if (color === null || color === undefined) {
+    return 'rgba(0, 0, 0, 0)';
+  }
+
+  // processColor 在 web 上回傳的格式是 AARRGGBB (32-bit integer)
+  const intValue = color >>> 0; // 確保是 unsigned
+  const a = ((intValue >> 24) & 0xff) / 255;
+  const r = (intValue >> 16) & 0xff;
+  const g = (intValue >> 8) & 0xff;
+  const b = intValue & 0xff;
+
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+/**
+ * 根據 direction 取得 CSS linear-gradient 的方向
+ */
+function getGradientDirection(direction: GradientMaskViewProps['direction']): string {
+  switch (direction) {
+    case 'top':
+      return 'to bottom'; // 頂部透明 → 底部不透明
+    case 'bottom':
+      return 'to top'; // 底部透明 → 頂部不透明
+    case 'left':
+      return 'to right'; // 左側透明 → 右側不透明
+    case 'right':
+      return 'to left'; // 右側透明 → 左側不透明
+    default:
+      return 'to bottom';
+  }
+}
+
+/**
+ * 建立 CSS linear-gradient 字串
+ */
+function buildGradientString(
+  colors: (number | null)[],
+  locations: number[],
+  direction: GradientMaskViewProps['direction']
+): string {
+  const gradientDirection = getGradientDirection(direction);
+
+  const colorStops = colors.map((color, index) => {
+    const rgba = colorToRgba(color);
+    const location = locations[index] !== undefined ? locations[index] * 100 : (index / (colors.length - 1)) * 100;
+    return `${rgba} ${location}%`;
+  });
+
+  return `linear-gradient(${gradientDirection}, ${colorStops.join(', ')})`;
+}
+
+/**
+ * 根據 maskOpacity 調整顏色的 alpha 值
+ * maskOpacity = 0 時，所有顏色變為完全不透明（無遮罩效果）
+ * maskOpacity = 1 時，保持原本的 alpha 值
+ */
+function adjustColorsForOpacity(
+  colors: (number | null)[],
+  maskOpacity: number
+): (number | null)[] {
+  if (maskOpacity >= 1) return colors;
+  if (maskOpacity <= 0) {
+    // 全部變成不透明黑色，表示內容完全可見
+    return colors.map(() => 0xff000000);
+  }
+
+  return colors.map((color) => {
+    if (color === null || color === undefined) return color;
+    const intValue = color >>> 0;
+    const a = ((intValue >> 24) & 0xff) / 255;
+    const r = (intValue >> 16) & 0xff;
+    const g = (intValue >> 8) & 0xff;
+    const b = intValue & 0xff;
+    // 根據 maskOpacity 調整 alpha：當 maskOpacity = 0 時 alpha 趨近於 1（完全可見）
+    const adjustedAlpha = a + (1 - a) * (1 - maskOpacity);
+    return ((Math.round(adjustedAlpha * 255) << 24) | (r << 16) | (g << 8) | b) >>> 0;
+  });
+}
+
+/**
+ * GradientMaskView - Web 實作
+ * 使用 CSS mask-image 搭配 linear-gradient 實現漸層遮罩效果
+ */
+export default function GradientMaskView(props: GradientMaskViewProps) {
+  const {
+    colors,
+    locations,
+    direction = 'top',
+    maskOpacity = 1,
+    style,
+    children,
+  } = props;
+
+  const maskStyle = React.useMemo(() => {
+    if (maskOpacity <= 0) {
+      // 無遮罩效果
+      return {};
+    }
+
+    const adjustedColors = adjustColorsForOpacity(colors, maskOpacity);
+    const gradientString = buildGradientString(adjustedColors, locations, direction);
+
+    return {
+      WebkitMaskImage: gradientString,
+      maskImage: gradientString,
+    };
+  }, [colors, locations, direction, maskOpacity]);
+
+  return (
+    <View style={[styles.container, style, maskStyle as any]}>
+      {children}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    overflow: 'hidden',
+  },
+});

package/src/index.ts

@@ -0,0 +1,7 @@
+// Reexport the native module. On web, it will be resolved to GradientMaskModule.web.ts
+// and on native platforms to GradientMaskModule.ts
+export { default } from './GradientMaskModule';
+export { default as GradientMaskView } from './GradientMaskView';
+export { default as AnimatedGradientMaskView } from './AnimatedGradientMaskView';
+export type { AnimatedGradientMaskViewProps } from './AnimatedGradientMaskView';
+export * from './GradientMask.types';

package/tsconfig.json

@@ -0,0 +1,9 @@
+// @generated by expo-module-scripts
+{
+  "extends": "expo-module-scripts/tsconfig.base",
+  "compilerOptions": {
+    "outDir": "./build"
+  },
+  "include": ["./src"],
+  "exclude": ["**/__mocks__/*", "**/__tests__/*", "**/__rsc_tests__/*"]
+}